ears 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1bc62c3b6367b99bdd80d44f670f79bd38709587df8e0bbcb72201772b99a74
-  data.tar.gz: b2fd12a20e5b0879fc1a69efe3729e6a422f8cc20f57007098a4da21d0198b4c
+  metadata.gz: d26c2fc5a7c55ba2a002cb8137232e06168e84d79a37b3d4f25f404304ce7cbe
+  data.tar.gz: 002ba87fc6d46b3ec4f0b9ed12626b1f3b13d2a41b44685416a329a65d1d20b8
 SHA512:
-  metadata.gz: 21299077971e38f928ef72d047726ad99218fc6d4b3c0d73cdd9a179f0cf87d8d5fab6f129a7d4c5dd20d97190d3d1d73daf81f229f3bd79cb21d60a73c9af95
-  data.tar.gz: 8e92b3f7bba6f494fd563f210dd43f03a95e4df0bf1f722dd1a6a3052fee9c82038679d8e7568a0de5e1e6581cdb343caa6092cc151f63890c2105a0da3b8134
+  metadata.gz: 05cae7fcff052959abf699b26d02f5024f2ef00793d0424f98f899efc9ceb898b8188c08b63671239663a9bdd950b359a9abe5697318347b4c4f58b3ee9561d7
+  data.tar.gz: 84a75eafa821fba5550bc1a2cc020b49b460473fee2cf0de8bba7b5520e74dca7734505e44996e40515c89b33fe1e7a73dfa6849d48eb67feee31820eab5746a

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.0 (2021-12-06)
+
+- add options to create retry and error queues
+
 ## 0.6.0 (2021-11-18)
 
 - add `connection_name` to configuration and make it a mandatory setting

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ears (0.6.0)
+    ears (0.7.0)
       bunny
       multi_json
 

data/README.md

@@ -156,6 +156,48 @@ Ears.setup do
 end
 ```
 
+### Implementing a retrying queue
+
+Sometimes you want to automatically retry processing a message, in case it just failed due to temporary problems. In that case, you can set the `retry_queue` and `retry_delay` parameters when creating the queue.
+
+```ruby
+my_queue =
+  queue('my_queue', durable: true, retry_queue: true, retry_delay: 5000)
+```
+
+This will automatically create a queue named `my_queue.retry` and use the arguments `x-dead-letter-exchange` and `x-dead-letter-routing-key` to route rejected messages to it. When routed to the retry queue, messages will wait there for the number of milliseconds specified in `retry_delay`, after which they will be redelivered to the original queue.
+
+This will happen indefinitely, so if you want to bail out of this cycle at some point, it is best to use the `error_queue` option to create an error queue and then use the `MaxRetries` middleware to route messages to this error queue after a certain amount of retries.
+
+### Implementing an error queue
+
+You can set the `error_queue` parameter to automatically create an error queue.
+
+```ruby
+my_queue =
+  queue(
+    'my_queue',
+    durable: true,
+    retry_queue: true,
+    retry_delay: 5000,
+    error_queue: true,
+  )
+```
+
+This will automatically create a queue named `my_queue.error`. It does not have any special properties, the helper's main purpose is to enforce naming conventions. In your consumer, you should then use the `MaxRetries` middleware to route messages to the error queue after a certain amount of retries.
+
+```ruby
+class MyConsumer < Ears::Consumer
+  use Ears::Middlewares::MaxRetries, retries: 3, error_queue: 'my_queue.error'
+
+  def work(delivery_info, metadata, payload)
+    # ...
+  end
+end
+```
+
+This will automatically route messages to `my_queue.error` after they have been re-tried three times. This prevents you from infinitely retrying a faulty message.
+
 ## Documentation
 
 If you need more in-depth information, look at [our API documentation](https://www.rubydoc.info/gems/ears).

data/lib/ears/setup.rb

@@ -5,6 +5,8 @@ require 'ears/consumer_wrapper'
 module Ears
   # Contains methods used in {Ears.setup} to set up your exchanges, queues and consumers.
   class Setup
+    QUEUE_PARAMS = %i[retry_queue retry_delay error_queue]
+
     # Creates a new exchange if it does not already exist.
     #
     # @param [String] name The name of the exchange.
@@ -19,9 +21,22 @@ module Ears
     #
     # @param [String] name The name of the queue.
     # @param [Hash] opts The options for the queue. These are passed on to +Bunny::Exchange.new+.
+    # @option args [Boolean] :retry_queue (false) Whether a retry queue should be created. The retry queue is configured as a dead-letter-exchange of the original queue automatically. The name of the queue will be the given name suffixed with ".retry".
+    # @option args [Integer] :retry_delay (5000) How long (in ms) a retried message is delayed before being routed back to the original queue.
+    # @option args [Boolean] :error_queue (false) Whether an error queue should be created. The name of the queue will be the given name suffixed with ".error".
     # @return [Bunny::Queue] The queue that was either newly created or was already there.
     def queue(name, opts = {})
-      Bunny::Queue.new(Ears.channel, name, opts)
+      bunny_opts = opts.reject { |k, _| QUEUE_PARAMS.include?(k) }
+      retry_delay = opts.fetch(:retry_delay, 5000)
+
+      create_retry_queue(name, retry_delay, bunny_opts) if opts[:retry_queue]
+      create_error_queue(name, bunny_opts) if opts[:error_queue]
+
+      Bunny::Queue.new(
+        Ears.channel,
+        name,
+        bunny_opts.merge(retry_opts(name, opts)),
+      )
     end
 
     # Creates and starts one or many consumers bound to the given queue.
@@ -46,6 +61,19 @@ module Ears
 
     private
 
+    def retry_opts(name, opts)
+      if opts[:retry_queue]
+        {
+          arguments: {
+            'x-dead-letter-exchange' => '',
+            'x-dead-letter-routing-key' => "#{name}.retry",
+          },
+        }
+      else
+        {}
+      end
+    end
+
     def create_consumer(queue, consumer_class, args, number)
       ConsumerWrapper.new(
         consumer_class.new,
@@ -69,5 +97,27 @@ module Ears
     def create_consumer_queue(queue, args)
       Bunny::Queue.new(create_consumer_channel(args), queue.name, queue.options)
     end
+
+    def create_retry_queue(name, delay, opts)
+      Bunny::Queue.new(
+        Ears.channel,
+        "#{name}.retry",
+        opts.merge(retry_queue_opts(name, delay)),
+      )
+    end
+
+    def retry_queue_opts(name, delay)
+      {
+        arguments: {
+          'x-message-ttl' => delay,
+          'x-dead-letter-exchange' => '',
+          'x-dead-letter-routing-key' => name,
+        },
+      }
+    end
+
+    def create_error_queue(name, opts)
+      Bunny::Queue.new(Ears.channel, "#{name}.error", opts)
+    end
   end
 end

data/lib/ears/version.rb

@@ -1,3 +1,3 @@
 module Ears
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ears
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Mario Mainz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-18 00:00:00.000000000 Z
+date: 2021-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny