jackhammer 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 232498851115b9f31c67a674fd67bb003fed1913c217eb0b1bd8418ea04ff804
-  data.tar.gz: febc0c5efee22668cf8c747eda637c50f53d7b307ae58376fce753ad34981f04
+  metadata.gz: 7cee97f6076b1008ddb323c8c43c87680cb334482569107992ac683c869fea7f
+  data.tar.gz: ee0aa15bb52690dba58a1145878d9d81fd1c33e3a802ef1290ee1fb584466898
 SHA512:
-  metadata.gz: 97135ef2215f4a5d9ae1a584287c01d1f3067f555a488ebc18d1692bcaa6fd8350ff4e0391bf9b10d7345f904364c071f8bc9669415f77263bd446bbb43e5be2
-  data.tar.gz: d21958748db93bd0dba6553374f58d7ced4ecec880f3203cec0385a4f0e4fd1d0555cdb8c02ee8cb4703f8aafe34402c0d3dfdddd9fd6067b8ebadc6848fab36
+  metadata.gz: 0d2d839de4fc36c47958b86b2f9e8f7857535b640ea86852ced3d4c79b93eb7c5e550035be7364e9a7f7b4e78c094bca93190c19322cf585b8dc483d1cb7ea0a
+  data.tar.gz: 9eb24d185af0730c0f17cb2fd8094d06604e5cb7548a44e6a2e1d1d0710970bef920e14455b38eaee447df4265c21de4529ddc85c31049c14b5536050d8411cf

data/.travis.yml

@@ -5,4 +5,5 @@ cache: bundler
 rvm:
   - 2.5
   - 2.6
+  - ruby-head
 before_install: gem install bundler -v 2.0.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jackhammer (0.1.1)
+    jackhammer (0.2.0)
       bunny (~> 2.14)
 
 GEM

data/README.md

@@ -1,3 +1,7 @@
+[![Build Status](https://travis-ci.org/RenoFi/jackhammer.svg?branch=master)](https://travis-ci.org/RenoFi/jackhammer)
+[![GitHub issues](https://img.shields.io/github/issues/renofi/jackhammer)](https://github.com/renofi/jackhammer/issues)
+[![GitHub license](https://img.shields.io/github/license/renofi/jackhammer)](https://github.com/RenoFi/jackhammer/blob/master/LICENSE.txt)
+
 # Jackhammer
 
 Jackhammer is an opinionated, configurable facade over the RabbitMQ Bunny
@@ -7,9 +11,7 @@ module.
 
 Add this line to your application's Gemfile:
 
-```ruby
-gem 'jackhammer'
-```
+    gem 'jackhammer'
 
 And then execute:
 
@@ -21,10 +23,12 @@ Or install it yourself as:
 
 ## Usage
 
+### Quick Start
+
 Create a YAML file to configure topics and queues your Jackhammer::Server instance
 will subscribe to when using the executable.
 
-```YAML
+```yaml
 # config/jackhammer.yml
 ---
 default: &default
@@ -42,7 +46,7 @@ default: &default
 development:
   <<: *default
 
-development:
+test:
   <<: *default
 
 production:
@@ -51,20 +55,21 @@ production:
 
 Configure your subscription server by sublcassing `Jackhammer::Server`.
 
-```Ruby
+```ruby
 # config/application.rb
 require 'jackhammer'
 
 module MyApp
   class Server < Jackhammer::Server
-    Jackhammer.configure do |jack|
-      jack.connection_options = {}
-      jack.connection_url =     nil
-      jack.environment =        ENV['RACK_ENV'] || :development
-      jack.exception_adapter =  NullExceptionAdapter.new
-      jack.logger =             Logger.new(IO::NULL)
-      jack.publish_options =    { mandatory: true, persistent: true }
-      jack.yaml_config =        "config/jackhammer.yml"
+    configure do |config|
+      # these are the default options
+      config.connection_options = {}
+      config.connection_url     = nil
+      config.environment        = ENV['RACK_ENV'] || :development
+      config.exception_adapter  = proc { |e| raise e }
+      config.logger             = Logger.new(IO::NULL)
+      config.publish_options    = { mandatory: true, persistent: true }
+      config.yaml_config        = "config/jackhammer.yml"
     end
   end
 end
@@ -72,9 +77,74 @@ end
 
 Start the subscription server to read the YAML and subscribe to topic queues.
 
+    $ bundle exec jackhammer
+
+### Topic Exchange Configuration
+
+The YAML file configures [RabbitMQ Topic Exchanges](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchange-topic).
+
+At the root are environment names used to load environment specific
+configuration. Below that are the names of topic exchanges.  Each topic exchange
+can define `durable` and `auto_delete` options used when creating the exchange.
+Additionally, each topic exchange defines a `queues` mapping.  Each mapping
+nested under the `queues` key represents options used by either Jackhammer or
+Bunny.
+
+Exchange topic queue options passed to Bunny during [queue initialization](http://reference.rubybunny.info/Bunny/Queue.html#initialize-instance_method):
+
+- **durable** default: false — Should this queue be durable?
+- **auto_delete** default: false — Should this queue be automatically deleted when the last consumer disconnects?
+- **exclusive** default: false — Should this queue be exclusive (only can be used by this connection, removed when the connection is closed)?
+
+The **routing_key** is used as an option when binding the Bunny::Queue and
+Bunny::Exchange.
+
+Exchange topic queue options used by Jackhammer:
+
+- **handler** A string representing the name of a class that is intended to
+  receive messages delivered to the queue subscriber.
+
+The handler class must implement at least a `.call` method. If the class
+responds to `.perform_async` then that will be called instead of `.call`.
+
+```ruby
+module MyApp
+  class SouthAmericaHandler
+    def self.call(message)
+      puts message
+    end
+  end
+end
 ```
-$ bundle exec jackhammer -r config/application.rb
-```
+
+### Executable
+
+By default the executable will load `config/application.rb`. If you define
+and configure your Jackhammer server somewhere else, use the `-r path/file.rb`
+option on the command line.
+
+    $ bundle exec jackhammer -r config/rabbitmq_application.rb
+
+### Server  Configuration
+
+The `configure` block must be placed inside of your application class even if
+you choose not to change any default configuration.
+
+The intent of the options might not be obvious by looking at the name.
+- **connection_options** passed into `Bunny.new`.
+- **connection_url** passed into `Bunny.new`.
+- **environment** specifies the section of YAML config to load.
+- **exception_adapter** exceptions caught when handling received messages are
+  forwarded to the adapter object. The adapter must implement
+  `.call(exception)`.
+- **logger** defines a logger the Jackhammer module should use.
+- **publish_options** defines options passed to all messages published (can be
+  overridden by passing the same options as arguments in your code).
+- **yaml_config** defines the file location of the Topic Exchange YAML
+  configuration file.
+
+You can find defaults specified in the Jackhammer::Configuration class
+constructor.
 
 ## Development
 
@@ -84,7 +154,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jackhammer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/renofi/jackhammer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/jackhammer.gemspec

@@ -2,7 +2,7 @@
 
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'jackhammer'
+require 'jackhammer/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'jackhammer'

data/lib/jackhammer.rb

@@ -6,13 +6,11 @@ require 'yaml'
 require 'bunny'
 require 'jackhammer/version'
 require 'jackhammer/log'
-require 'jackhammer/null_exception_adapter'
 require 'jackhammer/configuration'
 require 'jackhammer/message_receiver'
 require 'jackhammer/queue'
 require 'jackhammer/topic'
 require 'jackhammer/topic_manager'
-require 'jackhammer/publish'
 require 'jackhammer/server'
 
 module Jackhammer

data/lib/jackhammer/configuration.rb

@@ -17,7 +17,7 @@ module Jackhammer
       @connection_options = {}
       @connection_url = ENV['RABBITMQ_URL']
       @environment = ENV['RACK_ENV'] || :development
-      @exception_adapter = NullExceptionAdapter.new
+      @exception_adapter = proc { |e| raise e }
       @logger = Logger.new IO::NULL
       @publish_options = { mandatory: true, persistent: true }
       @yaml_config = './config/jackhammer.yml'

data/lib/jackhammer/queue.rb

@@ -13,7 +13,7 @@ module Jackhammer
         @handler_object.call content
       rescue StandardError => e
         Log.error e
-        Jackhammer.configuration.exception_adapter.capture e
+        Jackhammer.configuration.exception_adapter.call e
       end
     end
   end

data/lib/jackhammer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jackhammer
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jackhammer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Scott Serok
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-13 00:00:00.000000000 Z
+date: 2019-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -149,8 +149,6 @@ files:
 - lib/jackhammer/configuration.rb
 - lib/jackhammer/log.rb
 - lib/jackhammer/message_receiver.rb
-- lib/jackhammer/null_exception_adapter.rb
-- lib/jackhammer/publish.rb
 - lib/jackhammer/queue.rb
 - lib/jackhammer/server.rb
 - lib/jackhammer/topic.rb

data/lib/jackhammer/null_exception_adapter.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Jackhammer
-  class NullExceptionAdapter
-    # does nothing with any rescued exceptions
-    def capture(_); end
-  end
-end

data/lib/jackhammer/publish.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Jackhammer
-  # The API to send messages to a topic with a given attribute
-  class Publish
-    class << self
-      def topics
-        @topics ||= {}
-      end
-
-      def publish(event, message, options)
-        publish_options = Jackhammer.configuration.publish_options # system defaults
-        publish_options[:routing_key] = event                   # routing_key
-        publish_options = publish_options.merge options         # override any system defaults
-        Jackhammer.connection.publish message, publish_options
-      end
-    end
-  end
-end