event_people 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6d904d51b4d70c11a857e96579c5faada37cd4a41c386fb7f640ec623b62cc6
-  data.tar.gz: f75a42c90be3495a3e05cc51db564773380014ab09cf9bf1ae85e5b4c0cdf3ee
+  metadata.gz: c7f60b5a8806b69e26b0f66ea3a547e92200f460df4f30a2df90eed2fa08641d
+  data.tar.gz: 343c7a4e19f4a0194e552b507f3d000a1fd723faf374a35faee8961527c1809f
 SHA512:
-  metadata.gz: ade6969611ece666b6082dcbfb5e9cbf517628139c6dc9a189e7f25c22e42060dff26d19969793e43fb47a785cd16cc88b097b027a0f3cdeab89118c8ed28740
-  data.tar.gz: ee304195e724aa495f8fe58b8fbd9f32cc4e12000feb539f275862a74b3b976d733bb12671ff35558fba1598b3ba5b8cf229620022e27384d98ba3d74c62d76b
+  metadata.gz: dbd234e3c4df60f769feb130c05b8d96421677e8e297704b5620f41749ba3a507bfae2d22af9c020612d5fbb2b1f426bc427b8e71f476235de68a1fb806e1e38
+  data.tar.gz: 791f1ee04535ed6eef1d3fd9cb5771da399b336b946d9b4fef7f46b43d362781c6698a26aafac727620ef792f93a2f8fab6f2e59f3460655073c8a2937ab8600

data/.event_people.yml

@@ -1,5 +1,5 @@
-spec_version: "1.1.0"
-implementation_version: "1.1.0"
+spec_version: "1.1.1"
+implementation_version: "1.2.1"
 language: ruby
 package: "event_people (RubyGems)"
 status: stable
@@ -19,9 +19,6 @@ implemented:
   - RabbitContext
   - Topic
   - Queue
-
-# Spec components not yet implemented (pending in spec too)
-pending:
   - RetryManager
   - "Event.retryCount"
   - "Event.incrementRetryCount"
@@ -36,6 +33,9 @@ pending:
   - "RabbitContext.isLastRetry"
   - "RabbitContext.dlqName"
 
+# Spec components not yet implemented (pending in spec too)
+pending: []
+
 # Structural or naming departures from the spec
 # (Ruby module-qualified class names are an accepted adaptation, not a deviation)
 deviations: []

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    event_people (1.0.7)
+    event_people (1.2.0)
       bunny (~> 2.7)
 
 GEM

data/README.md

@@ -220,6 +220,65 @@ EventPeople::Daemon.start
 ```
 [See more details](https://github.com/pin-people/event_people_ruby/blob/master/examples/daemon.rb)
 
+## Retry and Dead Letter Queue (DLQ)
+
+### Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `RABBIT_EVENT_PEOPLE_MAX_RETRIES` | Max retry attempts before dead-lettering | `3` |
+| `RABBIT_EVENT_PEOPLE_RETRY_TTL_MS` | Base delay in ms for retry backoff | `1000` |
+
+### How it works
+
+On `context.fail`:
+- If retries remain → message published to `{queue}_retry` with exponential backoff delay, then acked
+- If retries exhausted → nacked to DLQ via RabbitMQ DLX
+
+On `context.reject` → nacked directly to DLQ (no retries)
+
+**Delay strategies:**
+- `exponential` (default): `min(initialDelay × 5^retry_count, 600000)` ms
+- `fixed`: constant `initialDelay` ms
+
+### Queue topology (auto-created on subscribe)
+
+| Queue/Exchange | Name | Purpose |
+|---|---|---|
+| Exchange (DLX) | `{app_name}_dlx` | Fanout, receives dead-lettered messages |
+| DLQ | `{app_name}_dlq` | Final resting place for failed messages |
+| Retry queue | `{queue_name}_retry` | Holds messages until backoff delay expires |
+
+### Usage
+
+```ruby
+class OrderListener < EventPeople::Listeners::Base
+  bind :handle_created, 'order.service.created'
+
+  def handle_created(event)
+    puts "Attempt #{event.retry_count + 1} of #{context.max_retries}"
+
+    if invalid?(event)
+      reject  # → DLQ immediately, no retries
+      return
+    end
+
+    process(event)
+    success
+  rescue StandardError
+    puts 'Final attempt, sending to DLQ' if context.is_last_retry
+    fail  # → retry queue (or DLQ if exhausted)
+  end
+end
+
+# Per-listener retry config (overrides env var defaults)
+EventPeople::Listener.on('order.service.created', method(:handle),
+                         max_attempts: 5,
+                         delay_strategy: 'exponential')
+```
+
+> **Note:** `success!`, `fail!`, `reject!` still work but are deprecated — prefer `success`, `fail`, `reject`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/event_people/broker/base.rb

@@ -15,13 +15,13 @@ module EventPeople
         raise NotImplementedError.new('Must be implemented')
       end
 
-      def self.consume(event_name, &block)
+      def self.consume(event_name, retry_config: {}, &block)
         consumers[event_name] ||= begin
-          new.consume(event_name, &block)
+          new.consume(event_name, retry_config: retry_config, &block)
         end
       end
 
-      def consume(event_name, &block)
+      def consume(event_name, retry_config: {}, &block)
         raise NotImplementedError.new('Must be implemented')
       end
 

data/lib/event_people/broker/context.rb

@@ -13,6 +13,14 @@ module EventPeople
         raise NotImplementedError.new('Must be implemented')
       end
 
+      def max_retries
+        raise NotImplementedError.new('Must be implemented')
+      end
+
+      def is_last_retry
+        raise NotImplementedError.new('Must be implemented')
+      end
+
       def success!
         warn '[DEPRECATED] EventPeople: `success!` is deprecated, use `success` instead. Will be removed in a future version.'
         success

data/lib/event_people/broker/rabbit/queue.rb

@@ -6,18 +6,21 @@ module EventPeople
         @channel.prefetch(1)
       end
 
-      def self.subscribe(channel, routing_key, &block)
-        new(channel).subscribe(routing_key, &block)
+      def self.subscribe(channel, routing_key, retry_config: {}, &block)
+        new(channel).subscribe(routing_key, retry_config: retry_config, &block)
       end
 
-      def subscribe(routing_key, &block)
+      def subscribe(routing_key, retry_config: {}, &block)
         base_name = routing_key.split('.')[0..2].join('.')
         name = queue_name("#{base_name}.all")
 
-        channel.queue(name, queue_options)
+        declare_dlx_and_dlq
+        declare_retry_queue(name)
+
+        channel.queue(name, main_queue_options)
                .bind(topic, routing_key: routing_key)
                .subscribe(manual_ack: true) do |delivery_info, properties, payload|
-                 callback(delivery_info, properties, payload, &block)
+                 callback(delivery_info, properties, payload, name, retry_config, &block)
                end
       end
 
@@ -25,11 +28,37 @@ module EventPeople
 
       attr_reader :channel
 
-      def callback(delivery_info, properties, payload, &block)
-        event_name = delivery_info.routing_key
+      def declare_dlx_and_dlq
+        dlx_name = "#{EventPeople::Config::APP_NAME}_dlx"
+        dlq_name = "#{EventPeople::Config::APP_NAME}_dlq"
+
+        dlx = channel.fanout(dlx_name, durable: true)
+        channel.queue(dlq_name, durable: true).bind(dlx, routing_key: '')
+      end
+
+      def declare_retry_queue(main_queue_name)
+        channel.queue("#{main_queue_name}_retry", durable: true, arguments: {
+          'x-dead-letter-exchange'    => '',
+          'x-dead-letter-routing-key' => main_queue_name
+        })
+      end
+
+      def callback(delivery_info, properties, payload, queue_name, retry_config, &block)
+        event_name  = delivery_info.routing_key
+        retry_count = [(properties.headers&.dig('x-event-people-retries') || 0).to_i, 0].max
+
+        event = EventPeople::Event.new(event_name, payload, 1.0, retry_count: retry_count)
 
-        event = EventPeople::Event.new(event_name, payload)
-        context = EventPeople::Broker::Rabbit::RabbitContext.new(channel, delivery_info)
+        context = EventPeople::Broker::Rabbit::RabbitContext.new(
+          channel,
+          delivery_info,
+          retry_count:      retry_count,
+          max_retries:      retry_config[:max_attempts],
+          delay_strategy:   retry_config[:delay_strategy],
+          dlq_name:         retry_config[:dlq_name],
+          queue_name:       queue_name,
+          original_payload: payload
+        )
 
         block.call(event, context)
       end
@@ -38,8 +67,11 @@ module EventPeople
         Rabbit::Topic.topic(channel)
       end
 
-      def queue_options
-        { durable: true }
+      def main_queue_options
+        {
+          durable:   true,
+          arguments: { 'x-dead-letter-exchange' => "#{EventPeople::Config::APP_NAME}_dlx" }
+        }
       end
 
       def queue_name(routing_key)

data/lib/event_people/broker/rabbit/rabbit_context.rb

@@ -1,9 +1,21 @@
 module EventPeople
   module Broker
     class Rabbit::RabbitContext < EventPeople::Broker::Context
-      def initialize(channel, delivery_info)
-        @channel = channel
-        @delivery_info = delivery_info
+      attr_reader :max_retries, :dlq_name
+
+      def initialize(channel, delivery_info, retry_count: 0, max_retries: nil, delay_strategy: nil, dlq_name: nil, queue_name: nil, original_payload: nil)
+        @channel          = channel
+        @delivery_info    = delivery_info
+        @retry_count      = retry_count.to_i
+        @max_retries      = (max_retries || EventPeople::Config::MAX_ATTEMPTS).to_i
+        @delay_strategy   = delay_strategy || EventPeople::Config::DELAY_STRATEGY
+        @dlq_name         = dlq_name || EventPeople::Config::DLQ_NAME
+        @queue_name       = queue_name
+        @original_payload = original_payload
+      end
+
+      def is_last_retry
+        @retry_count >= @max_retries - 1
       end
 
       def success
@@ -11,7 +23,37 @@ module EventPeople
       end
 
       def fail
-        @channel.nack(@delivery_info.delivery_tag, false, true)
+        retry_manager = Rabbit::RetryManager.new(@max_retries, @delay_strategy)
+
+        if retry_manager.should_retry?(@retry_count)
+          delay = retry_manager.get_next_delay(@retry_count)
+          begin
+            @channel.default_exchange.publish(
+              @original_payload,
+              routing_key: "#{@queue_name}_retry",
+              expiration: delay.to_s,
+              headers: { 'x-event-people-retries' => @retry_count + 1 }
+            )
+          rescue => e
+            # Publish failed — nack without requeue so the DLX routes to DLQ.
+            # Requeuing without incrementing x-event-people-retries would cause an infinite loop.
+            begin
+              @channel.nack(@delivery_info.delivery_tag, false, false)
+            rescue
+              # Channel may already be closed; nothing we can do.
+            end
+            raise e
+          end
+          begin
+            @channel.ack(@delivery_info.delivery_tag, false)
+          rescue
+            # Publish already succeeded; swallow ack errors. The message may be redelivered
+            # once (at-least-once), but that is safer than nacking to DLQ when a retry copy
+            # is already enqueued.
+          end
+        else
+          @channel.nack(@delivery_info.delivery_tag, false, false)
+        end
       end
 
       def reject
@@ -19,4 +61,4 @@ module EventPeople
       end
     end
   end
-end
+end

data/lib/event_people/broker/rabbit/retry_manager.rb

@@ -0,0 +1,25 @@
+module EventPeople
+  module Broker
+    class Rabbit::RetryManager
+      INITIAL_DELAY = (ENV['RABBIT_EVENT_PEOPLE_RETRY_TTL_MS'] || 1000).to_i
+      MAX_DELAY = 600_000
+
+      def initialize(max_attempts, delay_strategy = 'exponential')
+        @max_attempts   = max_attempts
+        @delay_strategy = delay_strategy
+      end
+
+      def should_retry?(retry_count)
+        retry_count < @max_attempts
+      end
+
+      def get_next_delay(retry_count)
+        if @delay_strategy == 'fixed'
+          INITIAL_DELAY
+        else
+          [INITIAL_DELAY * (5**retry_count), MAX_DELAY].min
+        end
+      end
+    end
+  end
+end

data/lib/event_people/broker/rabbit.rb

@@ -5,8 +5,8 @@ module EventPeople
         @@connection ||= session
       end
 
-      def consume(event_name, &block)
-        Queue.subscribe(channel, event_name, &block)
+      def consume(event_name, retry_config: {}, &block)
+        Queue.subscribe(channel, event_name, retry_config: retry_config, &block)
       end
 
       def produce(events)

data/lib/event_people/config.rb

@@ -6,8 +6,20 @@ module EventPeople
     URL      = ENV['RABBIT_URL']
     FULL_URL = "#{ENV['RABBIT_URL']}/#{ENV['RABBIT_EVENT_PEOPLE_VHOST']}"
 
+    MAX_ATTEMPTS   = (ENV['RABBIT_EVENT_PEOPLE_MAX_RETRIES'] || 3).to_i
+    DELAY_STRATEGY = 'exponential'
+    DLQ_NAME       = "#{ENV['RABBIT_EVENT_PEOPLE_APP_NAME']}_dlq"
+
     def self.broker
       EventPeople::Broker::Rabbit
     end
+
+    def self.get_retry_config
+      {
+        max_attempts:   MAX_ATTEMPTS,
+        delay_strategy: DELAY_STRATEGY,
+        dlq_name:       DLQ_NAME
+      }
+    end
   end
 end

data/lib/event_people/event.rb

@@ -1,11 +1,12 @@
 module EventPeople
   class Event
-    attr_reader :name, :headers, :body, :schema_version
+    attr_reader :name, :headers, :body, :schema_version, :retry_count
 
-    def initialize(name, body, schema_version = 1.0)
+    def initialize(name, body, schema_version = 1.0, retry_count: 0)
       @name = name
       @body = body.is_a?(String) ? JSON.parse(body) : body
       @schema_version = @body&.dig('headers', 'schemaVersion') || schema_version
+      @retry_count = retry_count.to_i
 
       if name?
         generate_headers
@@ -15,6 +16,10 @@ module EventPeople
       build_payload if @body&.key?('headers')
     end
 
+    def increment_retry_count
+      @retry_count += 1
+    end
+
     def payload
       { headers: headers, body: body }.to_json
     end

data/lib/event_people/listener.rb

@@ -2,16 +2,21 @@ require 'bunny'
 
 module EventPeople
   class Listener
-    def self.on(event_name, &block)
-      new.on(event_name, &block)
+    def self.on(event_name, max_attempts: nil, delay_strategy: nil, dlq_name: nil, &block)
+      new.on(event_name, max_attempts: max_attempts, delay_strategy: delay_strategy, dlq_name: dlq_name, &block)
     end
 
-    def on(event_name, &block)
+    def on(event_name, max_attempts: nil, delay_strategy: nil, dlq_name: nil, &block)
       raise(MissingAttributeError, 'Event name must be present') unless event_name&.size&.positive?
 
       event_name = consumed_event_name(event_name)
 
-      EventPeople::Config.broker.consume(event_name, &block)
+      retry_config = EventPeople::Config.get_retry_config
+      retry_config[:max_attempts]   = max_attempts   unless max_attempts.nil?
+      retry_config[:delay_strategy] = delay_strategy unless delay_strategy.nil?
+      retry_config[:dlq_name]       = dlq_name       unless dlq_name.nil?
+
+      EventPeople::Config.broker.consume(event_name, retry_config: retry_config, &block)
     end
 
     private

data/lib/event_people/version.rb

@@ -1,3 +1,3 @@
 module EventPeople
-  VERSION = '1.1.0'
+  VERSION = '1.2.1'
 end

data/lib/event_people.rb

@@ -11,6 +11,7 @@ require 'event_people/broker/context'
 require 'event_people/broker/rabbit'
 require 'event_people/broker/rabbit/queue'
 require 'event_people/broker/rabbit/rabbit_context'
+require 'event_people/broker/rabbit/retry_manager'
 require 'event_people/broker/rabbit/topic'
 
 module EventPeople

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_people
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Pin People
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -109,6 +109,7 @@ files:
 - lib/event_people/broker/rabbit.rb
 - lib/event_people/broker/rabbit/queue.rb
 - lib/event_people/broker/rabbit/rabbit_context.rb
+- lib/event_people/broker/rabbit/retry_manager.rb
 - lib/event_people/broker/rabbit/topic.rb
 - lib/event_people/config.rb
 - lib/event_people/daemon.rb