basquiat 1.2.0 → 1.3.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f2ece36298347faf2fb2607326545c2d35f78d08
-  data.tar.gz: e461978745bacda7cbf9e276327a91acdf814701
+  metadata.gz: 3e62fb7f48142250951c4e6c7d471fe3bbff47f4
+  data.tar.gz: 044bfbfdeeeec35150d679eae3425db38ab3699e
 SHA512:
-  metadata.gz: 88cfcff653f37e3f25519df53f4ca434af685cd6bc3146f4519e5b00c6efaea54c55fc2a051cbc131b8c92c734c77cc0d784bc83a2148aaccee463eb2857da15
-  data.tar.gz: 7c500da60290323968215415e264b2bbc698d5c1ac703212bf4bb2745b81ea704d78dae3cf371cab415cbac704032a0c8c23920417dfe1614bba41859bec901c
+  metadata.gz: fd73d055c57de8b20fd623876d270d18ddd8f0f8fd29443e76610dbd00c30dc5011010e49b1c3fa0f21a457a43a4a74f49ecdbe35db04e0b3bf9c759b743e545
+  data.tar.gz: e8e3af0254e4693d759defe4724f02bb4a6408c98df126303b214f491023fce078c57308967dbf37c72ded09d4eacb569b6d08cc3fc6db068e05cf55f04988dc

data/.codeclimate.yml

@@ -0,0 +1,50 @@
+# This is a sample .codeclimate.yml configured for Engine analysis on Code
+# Climate Platform. For an overview of the Code Climate Platform, see here:
+# http://docs.codeclimate.com/article/300-the-codeclimate-platform
+
+# Under the engines key, you can configure which engines will analyze your repo.
+# Each key is an engine name. For each value, you need to specify enabled: true
+# to enable the engine as well as any other engines-specific configuration.
+
+# For more details, see here:
+# http://docs.codeclimate.com/article/289-configuring-your-repository-via-codeclimate-yml#platform
+
+# For a list of all available engines, see here:
+# http://docs.codeclimate.com/article/296-engines-available-engines
+
+engines:
+# to turn on an engine, add it here and set enabled to `true`
+# to turn off an engine, set enabled to `false` or remove it
+  rubocop:
+    enabled: true
+  golint:
+    enabled: false
+  gofmt:
+    enabled: false
+  eslint:
+    enabled: false
+  csslint:
+    enabled: false
+
+# Engines can analyze files and report issues on them, but you can separately
+# decide which files will receive ratings based on those issues. This is
+# specified by path patterns under the ratings key.
+
+# For more details see here:
+# http://docs.codeclimate.com/article/289-configuring-your-repository-via-codeclimate-yml#platform
+
+# Note: If the ratings key is not specified, this will result in a 0.0 GPA on your dashboard.
+
+# ratings:
+#   paths:
+#   - app/**
+#   - lib/**
+#   - "**.rb"
+#   - "**.go"
+
+# You can globally exclude files from being analyzed by any engine using the
+# exclude_paths key.
+
+#exclude_paths:
+#- spec/**/*
+#- vendor/**/*

data/.gitignore

@@ -20,3 +20,4 @@ bin
 docker/Gemfile
 log
 .tags*
+doc

data/.metrics

@@ -1,10 +1,6 @@
 MetricFu::Configuration.run do |config|
   config.configure_metric(:cane) do |cane|
-    cane.line_length = 110
+    cane.line_length = 120
     cane.no_doc = 'y'
   end
-
-  config.configure_metric(:reek) do  |reek|
-    reek.config_file_pattern =  '.reek'
-  end
 end

data/.reek

@@ -1,3 +1,2 @@
----
 IrresponsibleModule:
   enabled: false

data/.rubocop.yml

@@ -3,8 +3,9 @@ AllCops:
     - 'bin/*'
     - 'docker/*'
     - 'Guardfile'
+    - 'basquiat.gemspec'
 Metrics/LineLength:
-  Max: 109
+  Max: 119
 
 Style/AlignHash:
   EnforcedHashRocketStyle: table

data/.ruby-version

@@ -1 +1 @@
-ruby-2.2
+ruby-2.2.3

data/Guardfile

@@ -16,3 +16,7 @@ guard :rubocop, { cmd: 'rubocop', cli: '-fs -c./.rubocop.yml' } do
   #watch(%r{.+\.rb$})
   #watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
 end
+
+guard 'yard', { cli: '-r' } do
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -1,97 +1,113 @@
 # Basquiat
 
-**Basquiat** is intended to hide (almost) all the complexity of working with some kind of message queue from the application internals.
+[![Code Climate](https://codeclimate.com/github/VAGAScom/basquiat/badges/gpa.svg)](https://codeclimate.com/github/VAGAScom/basquiat)
 
-All the exchanges, connections, queues and sessions declarations are swept under rug. The main aim is to provide a simple yet flexible interface to work with message queues.
+**Basquiat** is library aimed to hide (almost) all the complexity when working with some kind of message queue from the application internals.
+
+All the exchanges, connections, queues and sessions declarations are swept under rug. The aim is to provide a simple yet flexible interface to work with message queues.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'basquiat'
+```ruby
+gem 'basquiat'
+```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install basquiat
+```bash
+$ gem install basquiat
+```
 
-You will also need the right gem for your MQ system. Bundled in this gem you will find 2 adapters for RabbitMQ and ActiveMQ which depends on the gems _bunny_ and _ruby-stomp_ respectively.
+You will also need the right gem for your Message Queue (MQ) system. Bundled in this gem you will find 1 adapter, for RabbitMQ, which depends on the gem _bunny_.
 
 ## Basic Usage
 
-First of all require the gem, the dependecy for the adapter and the adapter itself
-
-    require 'basquiat'
-    require 'bunny'
-    require 'basquiat/adapters/rabbitmq_adapter'
+First of all require the gem, the dependency for the adapter and the adapter itself
 
-Then you can extend the class that you will use for communicating with the MQ
+```ruby
+require 'basquiat'
+require 'bunny'
+require 'basquiat/adapters/rabbitmq_adapter'
+```
 
-    class TownCrier
-      extend Basquiat::Base
-    end
+Then you can extend the class that you will use for communicating with the MQ, setting the adapter:
 
-From here you can publish events to the queue
-
-    TownCrier.publish('some.nifty.event', {a: 'hash', of: 'values'})
+```ruby
+class TownCrier
+  extend Basquiat::Base
+  self.event_adapter Basquiat::Adapters::RabbitMq
+end
+```
+From there you can publish events to the queue
 
+```ruby
+TownCrier.publish('some.nifty.event', {a: 'hash', of: 'values'})
+```
 And you can subscribe to one or more events using a proc that will get called when the message is received:
 
-    class TownCrier
-      extend Basquiat::Base
+```ruby
+class TownCrier
+  extend Basquiat::Base
 
-      subscribe_to 'some.nifty.event', ->(msg) { msg.fetch(:of, '').upcase }
-    end
+  subscribe_to 'some.nifty.event', ->(msg) { msg.fetch(:of, '').upcase }
+end
+```
 
 ## Configuration
 
 You can setup Basquiat using the configure method. This method will yield a Configuration object:
 
-    Basquiat.configure do |config|
-      config.exchange_name = 'my_exchange'
-    end
-
+```ruby
+Basquiat.configure do |config|
+  config.exchange_name = 'my_exchange'
+end
+```
 The available options are:
 
 - config_file= Receive a path to an YAML file (example here)
 - queue_name= The default queue name
 - exchange_name= The default exchange name
 - environment= Forces the environment to something other than the value of BASQUIAT_ENV
-- logger= The logger to be used. Defaults to a null logger.
-
-The configuration can be reset using the Basquiat.reset method.
-
-Yaml File configuration example:
-
-    test:                                       #environment
-      exchange_name: 'my.test_exchange'         #required
-      queue_name: 'my.nice_queue'               #required
-      default_adapter: Basquiat::Adapters::Test #it will overwrite the adapter on all classes that extend Basquiat::Base
-      adapter_options:                          #Adapter specific options
-        :servers:
-          -
-            :host: 'localhost'
-            :port: '5672'
-    development:                                #full example of the RabbitMq options 
-      exchange_name: 'my.exchange'
-      queue_name: 'my.queue'
-      default_adapter: Basquiat::Adapters::RabbitMq
-      adapter_options:
-        servers:
-          -
-            :host: 'localhost'
-            :port: '5672'
-        failover:
-          :default_timeout: 5
-          :max_retries: 5
-        publisher: 
-          confirm: true
-          persistent: true
-        auth:
-          user: 'guest'
-          password: 'guest' 
-        requeue:
-          enabled: false
+- logger= The logger to be used. Defaults to a null object logger.
+
+The configuration can be reset using the `Basquiat.reset` method.
+
+YAML File configuration example:
+
+```yaml
+test:                                       #environment
+  default_adapter: Basquiat::Adapters::Test #it will overwrite the adapter on all classes that extend Basquiat::Base
+  adapter_options:                          #Adapter specific options
+    servers:
+      -
+        host: 'localhost'
+        port: '98765'
+development:                                #full example of the RabbitMq options
+  exchange_name: 'basquiat.exchange'
+  queue_name: 'basquiat.queue'
+  default_adapter: Basquiat::Adapters::RabbitMq
+  adapter_options:
+    hosts:
+      - 'localhost'
+    port: 5672
+    publisher:
+      confirm: true
+      persistent: true
+    auth:
+      user: 'guest'
+      password: 'guest'
+    requeue:
+      enabled: true
+      delayed_delivery:
+        retries: 10
+        queue_name_preffix: wait.for_it
+        exchange_name: legendary
+```

data/basquiat.gemspec

@@ -27,14 +27,15 @@ EOD
   spec.add_development_dependency 'guard-bundler'
   spec.add_development_dependency 'guard-rspec'
   spec.add_development_dependency 'guard-rubocop'
+  spec.add_development_dependency 'guard-yard'
   spec.add_development_dependency 'bunny'
-  spec.add_development_dependency 'stomp'
   spec.add_development_dependency 'yajl-ruby'
   spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'metric_fu'
   spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'metric_fu'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'yard'
+
 
   spec.add_dependency 'multi_json'
   spec.add_dependency 'naught'

data/basquiat_docker.sh

@@ -30,6 +30,6 @@ function stop_and_remove_containers {
 
 generate_gemfile
 docker-compose start rabbitmq
-docker-compose run basquiat
+docker-compose run --service-ports basquiat
 
 trap stop_and_remove_containers EXIT SIGINT SIGTERM SIGKILL

data/docker/Dockerfile

@@ -1,10 +1,15 @@
-FROM mereghost/ruby:latest
-
-RUN useradd -m -g users dev
+FROM mereghost/ruby:2.2.2
 
+RUN useradd -mg users -G network dev
 VOLUME /basquiat
 WORKDIR /basquiat
 
 ENV REFRESHED_AT 2015-03-29
+USER dev
 COPY Gemfile /tmp/Gemfile
+
+#This is needed by bundler =/
+ENV GEM_HOME=/home/dev/.gem
 RUN cd /tmp && bundle install
+
+EXPOSE 8808

data/docker-compose.yml

@@ -5,11 +5,11 @@ basquiat:
     - ./:/basquiat
   links:
     - rabbitmq
-  tty: true
-  stdin_open: true
+  ports:
+    - "8808"
 
 rabbitmq:
-  image: mereghost/rabbitmq:latest
+  image: rabbitmq:3-management
   ports:
     - "15672"
     - "5672"

data/lib/basquiat/adapters/base_adapter.rb

@@ -8,54 +8,89 @@ module Basquiat
       using Basquiat::HashRefinements
 
       class << self
+        # A hash representing the registered requeue/acknowledge strategies
+        # @return [Hash] the registered RequeueStrategies
         def strategies
           @strategies ||= {}
         end
 
+        # Used to register a requeue/acknowledge strategy
+        # @param config_name [#to_sym] the named used on the config file for the Requeue Strategy
+        # @param klass [Class] the class name.
         def register_strategy(config_name, klass)
-          strategies.merge!(config_name.to_sym => klass)
+          strategies[config_name.to_sym] = klass
+        end
+
+        # Return the Strategy Class registered on key
+        # @param key [#to_sym] configured key for the wanted strategy
+        # @return [Class] return the strategy class
+        # @raise [Errors::StrategyNotRegistered] if it fails to find the key
+        def strategy(key)
+          strategies.fetch(key)
+        rescue KeyError
+          raise Basquiat::Errors::StrategyNotRegistered
         end
       end
 
-      def initialize
+      # @param procs: [Object]
+      #   It's a hash by default, but usually will be superseded by the adapter implementation
+      def initialize(procs: {})
         @options = base_options
-        @procs   = {}
+        @procs   = procs
         @retries = 0
       end
 
+      # Utility method to access the class instance variable
       def strategies
         self.class.strategies
       end
 
-      # Used to set the options for the adapter. It is merged in
-      # to the default_options hash.
+      # Allows the #base_options to be superseded on the local level
+      #
+      # You could have configured an exchange_name (on a config file) to +'awesome.sauce'+,
+      # but on this object you'd want to publish your messages to the +'killer.mailman'+ exchange.
+      # @example
+      #   class Mailmail
+      #     extend Basquiat::Base
+      #     adapter_options {exchange: {name: 'killer.mailman'}}
+      #   end
+      #
       # @param [Hash] opts an adapter dependant hash of options
       def adapter_options(opts)
         @options.deep_merge(opts)
       end
 
-      # Default options for the adapter
-      # @return [Hash]
+      # The default adapter options, merged with the {Basquiat::Configuration#adapter_options}. Used internally.
+      # @todo rename this method
+      # @return [Hash] the full options hash
       def base_options
         default_options.merge(Basquiat.configuration.adapter_options)
       end
 
+      # The adapter default options
+      # @return [Hash]
       def default_options
         {}
       end
 
+      # @!group Adapter specific implementations
+      # @abstract Publish an event to the event stream
       def publish
         fail Basquiat::Errors::SubclassResponsibility
       end
 
+      # @abstract subscribe_to the event stream
       def subscribe_to
         fail Basquiat::Errors::SubclassResponsibility
       end
 
+      # @abstract Disconnect from the message queue
       def disconnect
         fail Basquiat::Errors::SubclassResponsibility
       end
 
+      # @!endgroup
+
       private
 
       attr_reader :procs, :options

data/lib/basquiat/adapters/base_message.rb

@@ -1,29 +1,34 @@
 module Basquiat
   module Adapters
+    # The simplest Message class. It's encouraged to tailor it to your adapter needs (hence BaseMessage).
     class BaseMessage < SimpleDelegator
       attr_reader :action
 
+      # @param message [Object] It's assumed that message is some kind of JSON
+      # @note All unknown messages will be delegated to the resulting Hash
       def initialize(message)
         @message = Basquiat::Json.decode(message)
         super(@message)
         @action = :ack
       end
 
-      def ack?
-        fail Basquiat::Errors::SubclassResponsibility
+      # @!group Action Setters
+      # Sets the action to be taken after processing to be an ack.
+      # Here just in case as the default is to acknowledge the message.
+      def ack
+        @action = :ack
       end
 
-      def unack
-        fail Basquiat::Errors::SubclassResponsibility
+      # Sets the action to be taken after processing to be an nack / reject
+      def nack
+        @action = :nack
       end
 
+      # Sets the action to be taken after processing to be a requeue
       def requeue
-        fail Basquiat::Errors::SubclassResponsibility
-      end
-
-      def delay_redelivery
-        fail Basquiat::Errors::SubclassResponsibility
+        @action = :requeue
       end
+      # @!endgroup
     end
   end
 end

data/lib/basquiat/adapters/rabbitmq/configuration.rb

@@ -1,20 +1,26 @@
 module Basquiat
   module Adapters
     class RabbitMq
+      # Responsible for dealing with the overall configuration of the RabbitMQ adapter
       class Configuration
         using Basquiat::HashRefinements
 
         def initialize
-          @options = { failover:  { default_timeout: 5, max_retries: 5 },
-                       servers:   [{ host: 'localhost', port: 5672 }],
+          @options = { connection:
+                                  { hosts: ['localhost'],
+                                    port:  5672,
+                                    auth:  { user: 'guest', password: 'guest' }
+                                  },
                        queue:     {
-                           name:    Basquiat.configuration.queue_name,
-                           options: { durable: true } },
+                         name:    Basquiat.configuration.queue_name,
+                         durable: true,
+                         options: {} },
                        exchange:  {
-                           name:    Basquiat.configuration.exchange_name,
-                           options: { durable: true } },
+                         name:    Basquiat.configuration.exchange_name,
+                         durable: true,
+                         options: {} },
                        publisher: { confirm: true, persistent: false },
-                       auth:      { user: 'guest', password: 'guest' },
+                       consumer:  { prefetch: 1000, manual_ack: true },
                        requeue:   { enabled: false } }
         end
 
@@ -22,29 +28,38 @@ module Basquiat
           @options
         end
 
-        def merge_user_options(user_opts)
+        # Merges the user supplied options with the base ones
+        # @param user_opts [Hash{Symbol=>Object}]
+        # @option user_opts [Hash{Symbol=>Object}] :connection see {Connection#initialize}
+        # @option user_opts [Hash{Symbol=>Object}] :queue
+        # @option user_opts [Hash{Symbol=>Object}] :exchange
+        # @option user_opts [Hash{Symbol=>Object}] :publisher
+        # @option user_opts [Hash{Symbol=>Object}] :requeue
+        # @return [Hash] the configuration option hash
+        def merge_user_options(**user_opts)
           @options.merge!(user_opts)
         end
 
+        # @return [Hash] the connection options
         def connection_options
-          { servers:  @options[:servers],
-            failover: @options[:failover],
-            auth:     @options[:auth] }
+          @options[:connection]
         end
 
+        # @return [Hash] the session options
         def session_options
           { exchange:  @options[:exchange],
             publisher: @options[:publisher],
+            consumer:  @options[:consumer],
             queue:     @options[:queue] }.deep_merge(strategy.session_options)
         end
 
+        # @return [BaseStrategy] the requeue strategy or {BasicAcknowledge} if none is configured
         def strategy
-          return BasicAcknowledge unless @options[:requeue][:enabled]
-          @strategy ||= RabbitMq.strategies.fetch(@options[:requeue][:strategy].to_sym)
-          @strategy.setup(@options[:requeue][:options] || {})
+          requeue = @options[:requeue]
+          return AutoAcknowledge unless requeue[:enabled]
+          @strategy ||= RabbitMq.strategy(requeue[:strategy].to_sym)
+          @strategy.setup(requeue[:options] || {})
           @strategy
-        rescue KeyError
-          fail Basquiat::Errors::StrategyNotRegistered.new(@options[:requeue][:strategy])
         end
       end
     end