ears 0.6.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1bc62c3b6367b99bdd80d44f670f79bd38709587df8e0bbcb72201772b99a74
-  data.tar.gz: b2fd12a20e5b0879fc1a69efe3729e6a422f8cc20f57007098a4da21d0198b4c
+  metadata.gz: 7bc6c28c4597c7c985f8482edb10413d5877d1ec9bf1b937ccce30ffc7e78ea9
+  data.tar.gz: c6b55a0e1f0477970a7e451df4da4dc20ea35440c00cb4439d26f40949b9890c
 SHA512:
-  metadata.gz: 21299077971e38f928ef72d047726ad99218fc6d4b3c0d73cdd9a179f0cf87d8d5fab6f129a7d4c5dd20d97190d3d1d73daf81f229f3bd79cb21d60a73c9af95
-  data.tar.gz: 8e92b3f7bba6f494fd563f210dd43f03a95e4df0bf1f722dd1a6a3052fee9c82038679d8e7568a0de5e1e6581cdb343caa6092cc151f63890c2105a0da3b8134
+  metadata.gz: 7171678d307d67b703d7b63f2b338779bfd2d55ad9f3887e364d799043b811a6d3b97aa380b4a3f585fdb0cd7b97a3e7fe34cc764ed0acdd9cd9d7aac92d7fba
+  data.tar.gz: 27b9d05cc0807766b98ff46a5b0dbeeb357df7a1be60997706c4dc3a40b3002dd8ea8ae941398ef5238e6d6d0eb44baaa40b4b456e208de0f1bd9f511d1aef28

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.2 (2022-02-24)
+
+- change retry middleware to gracefully handle messages that do not have a header in their metadata
+
+## 0.7.1 (2021-12-21)
+
+- explicitly report Appsignal errors in middleware to make it more reliable
+
+## 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.2)
       bunny
       multi_json
 
@@ -54,7 +54,7 @@ GEM
       rubocop (~> 1.0)
       rubocop-ast (>= 1.1.0)
     ruby-progressbar (1.11.0)
-    set (1.0.1)
+    set (1.0.2)
     sorted_set (1.0.3)
       rbtree
       set (~> 1.0)

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. **Note that this will not automatically catch unhandled errors. You still have to catch any errors yourself and reject your message manually for the retry mechanism to work.**
+
+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/middlewares/appsignal.rb

@@ -14,17 +14,29 @@ module Ears
       end
 
       def call(delivery_info, metadata, payload, app)
+        start_transaction do
+          begin
+            app.call(delivery_info, metadata, payload)
+          rescue => e
+            ::Appsignal.set_error(e)
+            raise
+          end
+        end
+      end
+
+      private
+
+      attr_reader :transaction_name, :class_name
+
+      def start_transaction(&block)
         ::Appsignal.monitor_transaction(
           transaction_name,
           class: class_name,
           method: 'work',
           queue_start: Time.now.utc,
-        ) { app.call(delivery_info, metadata, payload) }
+          &block
+        )
       end
-
-      private
-
-      attr_reader :transaction_name, :class_name
     end
   end
 end

data/lib/ears/middlewares/max_retries.rb

@@ -30,6 +30,8 @@ module Ears
       end
 
       def retries_exceeded?(metadata)
+        return false if metadata.headers.nil?
+
         rejected_deaths =
           metadata
             .headers

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.2'
 end

metadata

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