hutch 0.21.0-java → 0.25.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ec88cab525084a9336085ec5eda85d8144816aa0
-  data.tar.gz: 91334a07d5ae533d7f0a1a332536ce1485d3e9f1
+SHA256:
+  metadata.gz: 46d709e9c94dfb88ee45ddc94792769e9e6f9f09d1b86adb394e7e18d11db9fa
+  data.tar.gz: 7b9e237c3e1f2b199ec42a7c5f39a9a86fb487fcda647d7e41fd87b5be3fe31d
 SHA512:
-  metadata.gz: dc0782ac33399218cb0a54c5ab33dc9dd6fc2ebdf816d5ef6f852620d780644005e2545c9d55e380fb14c08f40649cb65de8e250a62ca02918cb1fc67ae988d1
-  data.tar.gz: 5dd46544d97c5b2bd522327f85240f722cfe1b17911b23b53c0fb3c8210e2c04cb018fb615cbd4f7230c4c3d1376d64d1a09f46ca2cba3555680256007baa98e
+  metadata.gz: ef4ed43e500a37036bb7c9507bd42b832e0cf1eb0cbb38474e52652dc42bd5dba76eaa6acb85e30a55910bdaa5c1f076aa08ea0ff769c58769d60fae7d614537
+  data.tar.gz: 1db9d47abc7b1b1d6bde0fbd4eca448e0d267ce1dcf11295d85b849c7f8989f8cdec0a9beb3137f4652a38c794e7b6d91aee4188b1edffe3a16c362f33597f9f

data/.gitignore

@@ -5,3 +5,6 @@ Gemfile.lock
 .ruby-gemset
 .idea
 coverage
+.yardoc
+doc
+gemfiles/Gemfile.*.lock

data/.rspec

@@ -0,0 +1 @@
+--order random

data/.travis.yml

@@ -1,17 +1,16 @@
 language: ruby
 cache: bundler
-rvm:
-  - "2.3.0"
-  - "2.2"
-  - "2.1"
-  - "2.0"
-  - "jruby-9.0.0.0"
-
-sudo: false
+before_install:
+  - gem install bundler
+matrix:
+  include:
+    - rvm: 2.4.2
+    - rvm: 2.3.5
+    - rvm: 2.2.8
+    - rvm: jruby-9.1.15.0
+      jdk: oraclejdk8
+      env:
+        - JRUBY_OPTS='--debug'
 
 services:
   - rabbitmq
-
-matrix:
-  allow_failures:
-    - rvm: jruby-9.0.0.0

data/.yardopts

@@ -0,0 +1,5 @@
+--load "./lib/yard-settings/yard-settings.rb"
+--title "Hutch API docs"
+-
+README.md
+

data/CHANGELOG.md

@@ -1,4 +1,121 @@
-## 0.21.0 — (unreleased)
+## 0.25.0 — (unreleased)
+
+No changes yet.
+
+
+
+## 0.24.0 — February 1st, 2017
+
+### Configurable Consumer Prefixes
+
+Hutch consumers now can use user-provided prefixes for consumer tags.
+
+Contributed by Dávid Lantos.
+
+GitHub issue: [#265](https://github.com/gocardless/hutch/pull/265)
+
+### Signal Handling in Workers
+
+Hutch will now handle several OS signals:
+
+ * `USR2` will log stack traces of all alive VM threads
+ * `QUIT` (except on JRuby), `INT`, `TERM` will cause Hutch daemon to shut down
+ 
+ Contributed by Olle Jonsson.
+
+GitHub issues: [#263](https://github.com/gocardless/hutch/pull/263), [#271](https://github.com/gocardless/hutch/pull/271)
+
+### Opbeat Tracer
+
+Hutch now provides a tracer implementation for [Opbeat](https://opbeat.com/).
+
+Contributed by Olle Jonsson.
+
+GitHub issue: [#262](https://github.com/gocardless/hutch/pull/262)
+
+### `HUTCH_URI` Support
+
+The `HUTCH_URI` environment variable now can be used to configure
+Hutch connection URI.
+
+Contributed by Sam Stickland.
+
+GitHub issue: [#270](https://github.com/gocardless/hutch/pull/270)
+
+
+## 0.23.1 — October 20th, 2016
+
+This release contains a **breaking change** in the error
+handlers interface.
+
+### All Message Properties Passed to Error Handlers
+
+Previously error handlers were provided a message ID as first
+argument to `ErrorHandler#handle`. Now it is a hash of all message
+properties.
+
+This is a **breaking public API change**. If you do not use custom
+error handlers, you are not affected.
+
+Contributed by Pierre-Louis Gottfrois.
+
+GH issue: [hutch#238](https://github.com/gocardless/hutch/pull/238)
+
+### Opbeat Error Handler
+
+Contributed by Olle Jonsson.
+
+
+## 0.22.1 — June 7th, 2016
+
+### Message Payload is Reported to Sentry
+
+Contributed by Matt Thompson.
+
+### Daemonization Flag Ignored on JRuby
+
+Hutch will no longer try to daemonize its process on JRuby
+(since it is not supported) and will emit a warning instead.
+
+Contributed by Olle Jonsson.
+
+### Custom Setup Steps in Hutch::Worker
+
+`Hutch::Worker` now accepts a list of callables that are invoked
+after queue setup.
+
+Contributed by Kelly Stannard.
+
+### More Flexible and Better Abstracted Hutch::Broker
+
+`Hutch::Broker` was refactored with some bits extracted into separate
+classes or methods, making them easier to override.
+
+Contributed by Aleksandar Ivanov and Ryan Hosford.
+
+### Configurable Consumer Thread Pool Exception Handling (MRI only)
+
+`:consumer_pool_abort_on_exception` is a new option
+(defaults to `false`) which defines whether Bunny's
+consumer work pool threads should abort on exception.
+The option is ignored on JRuby.
+
+Contributed by Seamus Abshere.
+
+### Worker: Log received messages using level DEBUG instead of INFO
+
+Received messages used to be logged using severity level INFO. 
+This has been lowered to DEBUG.
+
+Contributed by Jesper Josefsson.
+
+### Refactoring
+
+Olle Jonsson and Kelly Stannard have contributed
+multiple internal improvements that have no behaviour changes.
+
+
+## 0.21.0 — February 7th, 2016
 
 ### JRuby Compatibility Restored
 

data/Gemfile

@@ -1,19 +1,30 @@
 source 'https://rubygems.org'
 
+ruby RUBY_VERSION
+
 gemspec
 
 group :development do
   gem "rake"
-  gem "guard", "~> 0.8.8"
-  gem "guard-rspec", "~> 0.5.4"
+  gem "guard", "~> 2.14", platform: :mri_23
+  gem "guard-rspec", "~> 4.7", platform: :mri_23
+
+  gem "yard", "~> 0.9"
+  gem 'kramdown', "> 0", platform: :jruby
+  gem "redcarpet", "> 0", platform: :mri
+  gem "github-markup", "> 0"
 end
 
 group :development, :test do
+  gem "rspec", "~> 3.5"
+  gem "simplecov", "~> 0.12"
+
   gem "sentry-raven"
   gem "honeybadger"
-  gem "coveralls", require: false
+  gem "coveralls", "~> 0.8.15", require: false
   gem "newrelic_rpm"
-  gem "airbrake"
+  gem "airbrake", "~> 7.0"
+  gem "opbeat", "~> 3.0.9"
 end
 
 group :development, :darwin do

data/Guardfile

@@ -1,5 +1,14 @@
-guard 'rspec', :version => 2, :cli => '--color --format doc' do
-  watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb') { "spec" }
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
 end

data/README.md

@@ -1,29 +1,47 @@
 ![](http://cl.ly/image/3h0q3F3G142K/hutch.png)
 
+[![Gem Version](https://badge.fury.io/rb/hutch.svg)](http://badge.fury.io/rb/hutch)
+[![Build Status](https://travis-ci.org/gocardless/hutch.svg?branch=master)](https://travis-ci.org/gocardless/hutch)
+[![Dependency Status](https://gemnasium.com/gocardless/hutch.svg)](https://gemnasium.com/gocardless/hutch)
+[![Code Climate](https://codeclimate.com/github/gocardless/hutch.svg)](https://codeclimate.com/github/gocardless/hutch)
+
 Hutch is a Ruby library for enabling asynchronous inter-service communication
 in a service-oriented architecture, using RabbitMQ.
 
-[![Gem Version](https://badge.fury.io/rb/hutch.png)](http://badge.fury.io/rb/hutch)
-[![Build Status](https://travis-ci.org/gocardless/hutch.png?branch=master)](https://travis-ci.org/gocardless/hutch)
-[![Dependency Status](https://gemnasium.com/gocardless/hutch.png)](https://gemnasium.com/gocardless/hutch)
-[![Code Climate](https://codeclimate.com/github/gocardless/hutch.png)](https://codeclimate.com/github/gocardless/hutch)
-
 To install with RubyGems:
 
 ```
-$ gem install hutch
+gem install hutch
 ```
 
-## Project Maturity
+<!-- Tocer[start]: Auto-generated, don't remove. -->
 
-Hutch is a moderately mature project (started in early 2013)
-that was extracted from production systems.
+### Table of Contents
 
+  - [Requirements](#requirements)
+  - [Overview](#overview)
+    - [Project Maturity](#project-maturity)
+  - [Consumers](#consumers)
+    - [Message Processing Tracers](#message-processing-tracers)
+  - [Running Hutch](#running-hutch)
+    - [Loading Consumers](#loading-consumers)
+    - [Stopping Hutch](#stopping-hutch)
+  - [Producers](#producers)
+    - [Producer Configuration](#producer-configuration)
+    - [Publisher Confirms](#publisher-confirms)
+    - [Writing Well-Behaved Publishers](#writing-well-behaved-publishers)
+  - [Configuration](#configuration)
+    - [Config File](#config-file)
+    - [Environment variables](#environment-variables)
+    - [Configuration precedence](#configuration-precedence)
+    - [Generated list of configuration options](#generated-list-of-configuration-options)
 
-## Supported Ruby Versions
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
 
-Hutch requires CRuby 2.0+ or JRuby 9K.
+## Requirements
 
+- Hutch requires Ruby 2.0+ or JRuby 9K.
+- Hutch requires RabbitMQ 3.3 or later.
 
 ## Overview
 
@@ -39,8 +57,12 @@ and so on. Publishers connect to RabbitMQ via `Hutch.connect` and publish using
 Hutch uses [Bunny](http://rubybunny.info) or [March Hare](http://rubymarchhare.info)
 (on JRuby) under the hood.
 
+### Project Maturity
 
-## Defining Consumers
+Hutch is a moderately mature project (started in early 2013)
+that was extracted from production systems.
+
+## Consumers
 
 Consumers receive messages from a RabbitMQ queue. That queue may be bound to
 one or more topics (represented by routing keys).
@@ -58,8 +80,8 @@ message[:id]  # => "02ABCXYZ"
 To subscribe to a topic, pass a routing key to `consume` in the class
 definition. To bind to multiple routing keys, simply pass extra routing keys
 in as additional arguments. Refer to the [RabbitMQ docs on topic exchanges
-][topic-docs] for more information about how to use routing keys. Here's an
-example consumer:
+](http://www.rabbitmq.com/tutorials/tutorial-five-ruby.html) for more information
+about how to use routing keys. Here's an example consumer:
 
 ```ruby
 class FailedPaymentConsumer
@@ -98,7 +120,9 @@ class FailedPaymentConsumer
 end
 ```
 
-Custom queue arguments can be found on [this page](https://www.rabbitmq.com/extensions.html).
+This sets the `x-max-length` header. For more details, see the [RabbitMQ
+documentation on Queue Length Limit](https://www.rabbitmq.com/maxlength.html). To find out more
+about custom queue arguments, consult the [RabbitMQ documentation on AMQP Protocol Extensions](https://www.rabbitmq.com/extensions.html). 
 
 Consumers can write to Hutch's log by calling the logger method. The logger method returns
 a [Logger object](http://ruby-doc.org/stdlib-2.1.2/libdoc/logger/rdoc/Logger.html).
@@ -107,7 +131,7 @@ a [Logger object](http://ruby-doc.org/stdlib-2.1.2/libdoc/logger/rdoc/Logger.htm
 class FailedPaymentConsumer
   include Hutch::Consumer
   consume 'gc.ps.payment.failed'
-  
+
   def process(message)
     logger.info "Marking payment #{message[:id]} as failed"
     mark_payment_as_failed(message[:id])
@@ -136,11 +160,13 @@ to learn more.
 
 Tracers allow you to track message processing.
 
-#### NewRelic
+This will enable NewRelic custom instrumentation:
+
 ```ruby
 Hutch::Config.set(:tracer, Hutch::Tracers::NewRelic)
 ```
-This will enable NewRelic custom instrumentation. Batteries included! Screenshoots available [here](https://monosnap.com/list/557020a000779174f23467e3).
+
+Batteries included! 
 
 ## Running Hutch
 
@@ -276,10 +302,10 @@ AMQP.connect(host: config[:host]) do |connection|
 end
 ```
 
-If using publisher confirms with amqp gem, see [this issue][pc-issue]
-and [this gist][pc-gist] for more info.
+If using publisher confirms with amqp gem, see [this issue](https://github.com/ruby-amqp/amqp/issues/92)
+and [this gist](https://gist.github.com/3042381) for more info.
 
-## Configuration Reference
+## Configuration
 
 ### Config File
 
@@ -317,10 +343,234 @@ Known configuration parameters are:
  * `write_timeout`: Bunny's socket write timeout (default: `11`)
  * `tracer`: tracer to use to track message processing
 
+### Environment variables
+
+The file configuration options mentioned above can also be passed in via environment variables, using the `HUTCH_` prefix, eg.
+
+ * `connection_timeout` &rarr; `HUTCH_CONNECTION_TIMEOUT`.
+
+### Configuration precedence
+
+In order from lowest to highest precedence:
+
+0. Default values
+0. `HUTCH_*` environment variables
+0. Configuration file
+0. Explicit settings through `Hutch::Config.set`
+
+### Generated list of configuration options
+
+Generate with
+
+0. `yard doc lib/hutch/config.rb`
+0. Copy the _Configuration_ section from `doc/Hutch/Config.html` here, with the anchor tags stripped.
+
+<table border="1" class="settings" style="overflow:visible;">
+  <thead>
+    <tr>
+      <th>
+        Setting name
+      </th>
+      <th>
+        Default value
+      </th>
+      <th>
+        Type
+      </th>
+      <th>
+        ENV variable
+      </th>
+      <th>
+        Description
+      </th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><tt>mq_host</tt></td>
+      <td>127.0.0.1</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_HOST</tt></td>
+      <td><p>RabbitMQ hostname</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_exchange</tt></td>
+      <td>hutch</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_EXCHANGE</tt></td>
+      <td><p>RabbitMQ Exchange to use for publishing</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_vhost</tt></td>
+      <td>/</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_VHOST</tt></td>
+      <td><p>RabbitMQ vhost to use</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_username</tt></td>
+      <td>guest</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_USERNAME</tt></td>
+      <td><p>RabbitMQ username to use.</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_password</tt></td>
+      <td>guest</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_PASSWORD</tt></td>
+      <td><p>RabbitMQ password</p></td>
+    </tr>
+    <tr>
+      <td><tt>uri</tt></td>
+      <td>nil</td>
+      <td>String</td>
+      <td><tt>HUTCH_URI</tt></td>
+      <td><p>RabbitMQ URI (takes precedence over MQ username, password, host, port and vhost settings)</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_api_host</tt></td>
+      <td>127.0.0.1</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_API_HOST</tt></td>
+      <td><p>RabbitMQ HTTP API hostname</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_port</tt></td>
+      <td>5672</td>
+      <td>Number</td>
+      <td><tt>HUTCH_MQ_PORT</tt></td>
+      <td><p>RabbitMQ port</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_api_port</tt></td>
+      <td>15672</td>
+      <td>Number</td>
+      <td><tt>HUTCH_MQ_API_PORT</tt></td>
+      <td><p>RabbitMQ HTTP API port</p></td>
+    </tr>
+    <tr>
+      <td><tt>heartbeat</tt></td>
+      <td>30</td>
+      <td>Number</td>
+      <td><tt>HUTCH_HEARTBEAT</tt></td>
+      <td><p><a href="http://rabbitmq.com/heartbeats.html">RabbitMQ heartbeat timeout</a></p></td>
+    </tr>
+    <tr>
+      <td><tt>channel_prefetch</tt></td>
+      <td>0</td>
+      <td>Number</td>
+      <td><tt>HUTCH_CHANNEL_PREFETCH</tt></td>
+      <td><p>The <tt>basic.qos</tt> prefetch value to use.</p></td>
+    </tr>
+    <tr>
+      <td><tt>connection_timeout</tt></td>
+      <td>11</td>
+      <td>Number</td>
+      <td><tt>HUTCH_CONNECTION_TIMEOUT</tt></td>
+      <td><p>Bunny's socket open timeout</p></td>
+    </tr>
+    <tr>
+      <td><tt>read_timeout</tt></td>
+      <td>11</td>
+      <td>Number</td>
+      <td><tt>HUTCH_READ_TIMEOUT</tt></td>
+      <td><p>Bunny's socket read timeout</p></td>
+    </tr>
+    <tr>
+      <td><tt>write_timeout</tt></td>
+      <td>11</td>
+      <td>Number</td>
+      <td><tt>HUTCH_WRITE_TIMEOUT</tt></td>
+      <td><p>Bunny's socket write timeout</p></td>
+    </tr>
+    <tr>
+      <td><tt>graceful_exit_timeout</tt></td>
+      <td>11</td>
+      <td>Number</td>
+      <td><tt>HUTCH_GRACEFUL_EXIT_TIMEOUT</tt></td>
+      <td><p>FIXME: DOCUMENT THIS</p></td>
+    </tr>
+    <tr>
+      <td><tt>consumer_pool_size</tt></td>
+      <td>1</td>
+      <td>Number</td>
+      <td><tt>HUTCH_CONSUMER_POOL_SIZE</tt></td>
+      <td><p>Bunny consumer work pool size</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_tls</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_MQ_TLS</tt></td>
+      <td><p>Should TLS be used?</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_verify_peer</tt></td>
+      <td>true</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_MQ_VERIFY_PEER</tt></td>
+      <td><p>Should SSL certificate be verified?</p></td>
+    </tr>
+    <tr>
+      <td><tt>mq_api_ssl</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_MQ_API_SSL</tt></td>
+      <td><p>Should SSL be used for the RabbitMQ API?</p></td>
+    </tr>
+    <tr>
+      <td><tt>autoload_rails</tt></td>
+      <td>true</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_AUTOLOAD_RAILS</tt></td>
+      <td><p>Should the current Rails app directory be required?</p></td>
+    </tr>
+    <tr>
+      <td><tt>daemonise</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_DAEMONISE</tt></td>
+      <td><p>Should the Hutch runner process daemonise?</p></td>
+    </tr>
+    <tr>
+      <td><tt>publisher_confirms</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_PUBLISHER_CONFIRMS</tt></td>
+      <td><p>Should RabbitMQ publisher confirms be enabled?</p></td>
+    </tr>
+    <tr>
+      <td><tt>force_publisher_confirms</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_FORCE_PUBLISHER_CONFIRMS</tt></td>
+      <td><p>Enables publisher confirms, forces Hutch::Broker#wait_for_confirms for</p></td>
+    </tr>
+    <tr>
+      <td><tt>enable_http_api_use</tt></td>
+      <td>true</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_ENABLE_HTTP_API_USE</tt></td>
+      <td><p>Should the RabbitMQ HTTP API be used?</p></td>
+    </tr>
+    <tr>
+      <td><tt>consumer_pool_abort_on_exception</tt></td>
+      <td>false</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_CONSUMER_POOL_ABORT_ON_EXCEPTION</tt></td>
+      <td><p>Should Bunny's consumer work pool threads abort on exception.</p></td>
+    </tr>
+    <tr>
+      <td><tt>consumer_tag_prefix</tt></td>
+      <td>hutch</td>
+      <td>String</td>
+      <td><tt>HUTCH_CONSUMER_TAG_PREFIX</tt></td>
+      <td><p>Prefix displayed on the consumers tags.</p></td>
+    </tr>
+  </tbody>
+</table>
 
-## Supported RabbitMQ Versions
-
-Hutch requires RabbitMQ 3.3 or later.
 
 ---