hutch 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5b96423188a88e607bf694005618e1c13bc6ce1
-  data.tar.gz: 97955f0060eea500cbd6cc49c3c393adccfaf8a6
+  metadata.gz: 9d93317d6750bca3658656b8b919dbdf9b277cf5
+  data.tar.gz: ce7f0b6bad0ea3764e13e634f764285f75927bdf
 SHA512:
-  metadata.gz: d161d2cf60136e26356a18f7a6f552fd11361bce6258132ce9dc807d219290f1fa67fda7f801fb58cacd542c224a93b4941c473aaa4c5ee3b43446632ab03c96
-  data.tar.gz: 7d2c9d3f0524a9583e76c853823a1527a9d516d7a2cf368aa061412442930e09d5a2b7855c915d4ab3e1ca8c39b2a82f0a864a6e51d558a420e1a9efd3d96cc1
+  metadata.gz: 6f39fa63c8d77ea71444ab25cfd599bfc89ad9e8c222323f69b322e66a179347fec7c1afb100b5575af08d1a6522af1d2e4adeef827c40f825313e76640482d9
+  data.tar.gz: d3c94ca6c2720fa3fd4197f408dc8832f9f904941dbd1cc556e13efae7b0768b2ab1be0c58159676cce4b78c0c5ccac9e15f8a55c780d6d251b0b42f54a55161

data/CHANGELOG.md

@@ -1,4 +1,68 @@
-## 0.19.0 — (unreleased)
+## 0.20.0 — (unreleased)
+
+### Hutch::Exception includes Bunny::Exception
+
+`Hutch::Exception` now inherits from `Bunny::Exception` which
+inherits from `StandardError`.
+
+GH issue: [#137](https://github.com/gocardless/hutch/issues/137).
+
+
+### Pluggable (Negative) Acknowledge Handlers
+
+Hutch now can be configured to use a user-provided
+object(s) to perform acknowledgement on consumer exceptions.
+
+For example, this is what the default handler looks like:
+
+``` ruby
+require 'hutch/logging'
+require 'hutch/acknowledgements/base'
+
+module Hutch
+  module Acknowledgements
+    class NackOnAllFailures < Base
+      include Logging
+
+      def handle(delivery_info, properties, broker, ex)
+        prefix = "message(#{properties.message_id || '-'}): "
+        logger.debug "#{prefix} nacking message"
+
+        broker.nack(delivery_info.delivery_tag)
+
+        # terminates further chain processing
+        true
+      end
+    end
+  end
+end
+```
+
+Handlers are configured similarly to exception notification handlers,
+via `:error_acknowledgements` in Hutch config.
+
+Contributed by Derek Kastner.
+
+GH issue: [#177](https://github.com/gocardless/hutch/pull/177).
+
+
+### Configurable Exchange Properties
+
+`:mq_exchange_options` is a new config option that can be used
+to provide a hash of exchange attributes (durable, auto-delete).
+The options will be passed directly to Bunny.
+
+Contributed by Derek Kastner.
+
+GH issue: [#170](https://github.com/gocardless/hutch/pull/170).
+
+
+### Bunny Update
+
+Bunny is updated to 2.2.1.
+
+
+## 0.19.0 — September 7th, 2015
 
 ### Pluggable Serialisers
 

data/README.md

@@ -20,6 +20,11 @@ Hutch is a moderately mature project (started in early 2013)
 that was extracted from production systems.
 
 
+## Supported Ruby Versions
+
+Hutch requires CRuby 2.0+ or JRuby 9K.
+
+
 ## Overview
 
 Hutch is a conventions-based framework for writing services that communicate
@@ -31,7 +36,8 @@ With Hutch, consumers are stored in separate files and include the `Hutch::Consu
 They are then loaded by a command line runner which connects to RabbitMQ, sets up queues and bindings,
 and so on. Publishers connect to RabbitMQ via `Hutch.connect` and publish using `Hutch.publish`.
 
-Hutch uses [Bunny](http://rubybunny.info) under the hood.
+Hutch uses [Bunny](http://rubybunny.info) or [March Hare](http://rubymarchhare.info)
+(on JRuby) under the hood.
 
 
 ## Defining Consumers
@@ -300,6 +306,10 @@ Known configuration parameters are:
                          tracked (e.g. using `Hutch::Broker#confirm_select` callback or `Hutch::Broker#wait_for_confirms`)
  * `force_publisher_confirms`: enables publisher confirms, forces `Hutch::Broker#wait_for_confirms` for every publish. **This is the safest option which also offers the lowest throughput**.
  * `log_level`: log level used by the standard Ruby logger (default: `Logger::INFO`)
+ * `error_handlers`: a list of error handler objects, see classes in `Hutch::ErrorHandlers`. All configured
+   handlers will be invoked unconditionally in the order listed.
+ * `error_acknowledgements`: a chain of responsibility of objects that acknowledge/reject/requeue messages when an
+    exception happens, see classes in `Hutch::Acknowledgements`.
  * `mq_exchange`: exchange to use for publishing (default: `hutch`)
  * `heartbeat`: [RabbitMQ heartbeat timeout](http://rabbitmq.com/heartbeats.html) (default: `30`)
  * `connection_timeout`: Bunny's socket open timeout (default: `11`)

data/hutch.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
     gem.add_runtime_dependency 'march_hare', '>= 2.11.0'
   else
     gem.platform = Gem::Platform::RUBY
-    gem.add_runtime_dependency 'bunny', '>= 2.2.0'
+    gem.add_runtime_dependency 'bunny', '>= 2.2.1'
   end
   gem.add_runtime_dependency 'carrot-top', '~> 0.0.7'
   gem.add_runtime_dependency 'multi_json', '~> 1.11.2'

data/lib/hutch/acknowledgements/base.rb

@@ -0,0 +1,16 @@
+module Hutch
+  module Acknowledgements
+    # Defines acknowledgement handler interface.
+    class Base
+      # Implements negative acknowledgement/requeueing logic
+      # and returns a boolean to indicate whether acknowledgement
+      # was performed. If false is returned, next handler in the
+      # chain will be invoked.
+      #
+      # The chain always falls back to unconditional nacking.
+      def handle(delivery_info, properties, broker, ex)
+        raise NotImplementedError.new
+      end
+    end
+  end
+end

data/lib/hutch/acknowledgements/nack_on_all_failures.rb

@@ -0,0 +1,19 @@
+require 'hutch/logging'
+require 'hutch/acknowledgements/base'
+
+module Hutch
+  module Acknowledgements
+    class NackOnAllFailures < Base
+      include Logging
+
+      def handle(delivery_info, properties, broker, ex)
+        prefix = "message(#{properties.message_id || '-'}): "
+        logger.debug "#{prefix} nacking message"
+
+        broker.nack(delivery_info.delivery_tag)
+
+        true
+      end
+    end
+  end
+end

data/lib/hutch/broker.rb

@@ -52,10 +52,11 @@ module Hutch
       open_channel!
 
       exchange_name = @config[:mq_exchange]
+      exchange_options = { durable: true }.merge @config[:mq_exchange_options]
       logger.info "using topic exchange '#{exchange_name}'"
 
       with_bunny_precondition_handler('exchange') do
-        @exchange = @channel.topic(exchange_name, durable: true)
+        @exchange = @channel.topic(exchange_name, exchange_options)
       end
     end
 

data/lib/hutch/config.rb

@@ -8,11 +8,12 @@ module Hutch
   module Config
     require 'yaml'
 
-    def self.initialize(params={})
+    def self.initialize(params = {})
       @config = {
         mq_host: 'localhost',
         mq_port: 5672,
         mq_exchange: 'hutch',  # TODO: should this be required?
+        mq_exchange_options: {},
         mq_vhost: '/',
         mq_tls: false,
         mq_tls_cert: nil,
@@ -32,6 +33,9 @@ module Hutch
         require_paths: [],
         autoload_rails: true,
         error_handlers: [Hutch::ErrorHandlers::Logger.new],
+        # note that this is not a list, it is a chain of responsibility
+        # that will fall back to "nack unconditionally"
+        error_acknowledgements: [],
         tracer: Hutch::Tracers::NullTracer,
         namespace: nil,
         daemonise: false,

data/lib/hutch/exceptions.rb

@@ -1,5 +1,8 @@
+require "bunny/exceptions"
+
 module Hutch
-  class Exception < StandardError; end
+  # Bunny::Exception inherits from StandardError
+  class Exception < Bunny::Exception; end
   class ConnectionError < Exception; end
   class AuthenticationError < Exception; end
   class WorkerSetupError < Exception; end

data/lib/hutch/version.rb

@@ -1,4 +1,4 @@
 module Hutch
-  VERSION = '0.19.0'.freeze
+  VERSION = '0.20.0'.freeze
 end
 

data/lib/hutch/worker.rb

@@ -1,6 +1,7 @@
 require 'hutch/message'
 require 'hutch/logging'
 require 'hutch/broker'
+require 'hutch/acknowledgements/nack_on_all_failures'
 require 'carrot-top'
 
 module Hutch
@@ -118,7 +119,7 @@ module Hutch
         with_tracing(consumer_instance).handle(message)
         broker.ack(delivery_info.delivery_tag)
       rescue StandardError => ex
-        broker.nack(delivery_info.delivery_tag)
+        acknowledge_error(delivery_info, properties, broker, ex)
         handle_error(properties.message_id, payload, consumer, ex)
       end
     end
@@ -133,11 +134,23 @@ module Hutch
       end
     end
 
+    def acknowledge_error(delivery_info, properties, broker, ex)
+      acks = error_acknowledgements +
+        [Hutch::Acknowledgements::NackOnAllFailures.new]
+      acks.find do |backend|
+        backend.handle(delivery_info, properties, broker, ex)
+      end
+    end
+
     def consumers=(val)
       if val.empty?
         logger.warn "no consumer loaded, ensure there's no configuration issue"
       end
       @consumers = val
     end
+
+    def error_acknowledgements
+      Hutch::Config[:error_acknowledgements]
+    end
   end
 end

data/spec/hutch/worker_spec.rb

@@ -63,6 +63,25 @@ describe Hutch::Worker do
       worker.handle_message(consumer, delivery_info, properties, payload)
     end
 
+    context 'when the consumer fails and a requeue is configured' do
+
+      it 'requeues the message' do
+        allow(consumer_instance).to receive(:process).and_raise('failed')
+        requeuer = double
+        allow(requeuer).to receive(:handle).ordered { |delivery_info, properties, broker, e|
+          broker.requeue delivery_info.delivery_tag
+          true
+        }
+        allow(worker).to receive(:error_acknowledgements).and_return([requeuer])
+        expect(broker).to_not receive(:ack)
+        expect(broker).to_not receive(:nack)
+        expect(broker).to receive(:requeue)
+
+        worker.handle_message(consumer, delivery_info, properties, payload)
+      end
+    end
+
+
     context 'when the consumer raises an exception' do
       before { allow(consumer_instance).to receive(:process).and_raise('a consumer error') }
 
@@ -95,5 +114,40 @@ describe Hutch::Worker do
       end
     end
   end
+
+
+  describe '#acknowledge_error' do
+    let(:delivery_info) { double('Delivery Info', routing_key: '',
+                                 delivery_tag: 'dt') }
+    let(:properties) { double('Properties', message_id: 'abc123') }
+
+    subject { worker.acknowledge_error delivery_info, properties, broker, StandardError.new }
+
+    it 'stops when it runs a successful acknowledgement' do
+      skip_ack = double handle: false
+      always_ack = double handle: true
+      never_used = double handle: true
+
+      allow(worker).
+        to receive(:error_acknowledgements).
+        and_return([skip_ack, always_ack, never_used])
+
+      expect(never_used).to_not receive(:handle)
+
+      subject
+    end
+
+    it 'defaults to nacking' do
+      skip_ack = double handle: false
+
+      allow(worker).
+        to receive(:error_acknowledgements).
+        and_return([skip_ack, skip_ack])
+
+      expect(broker).to receive(:nack)
+
+      subject
+    end
+  end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hutch
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Harry Marr
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-06 00:00:00.000000000 Z
+date: 2015-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: 2.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: 2.2.1
 - !ruby/object:Gem::Dependency
   name: carrot-top
   requirement: !ruby/object:Gem::Requirement
@@ -117,6 +117,8 @@ files:
 - examples/producer.rb
 - hutch.gemspec
 - lib/hutch.rb
+- lib/hutch/acknowledgements/base.rb
+- lib/hutch/acknowledgements/nack_on_all_failures.rb
 - lib/hutch/adapter.rb
 - lib/hutch/adapters/bunny.rb
 - lib/hutch/adapters/march_hare.rb