carnivore 0.2.0 → 0.2.2

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.2.2
+* Local loopback is optional and disabled by default
+* Include Smash utility for Hash management
+* Provide originating source to callback instances on initialization
+* Add spec helpers
+* Clean up custom supervisor implementation
+
 # v0.2.0
 * Remove `fog` from dependency list
 * Add common spec helper for testing

data/carnivore.gemspec

@@ -8,9 +8,11 @@ Gem::Specification.new do |s|
   s.email = 'chrisroberts.code@gmail.com'
   s.homepage = 'https://github.com/carnivore-rb/carnivore'
   s.description = 'Message processing helper'
+  s.license = 'Apache 2.0'
   s.require_path = 'lib'
   s.add_dependency 'celluloid'
   s.add_dependency 'mixlib-config'
   s.add_dependency 'multi_json'
+  s.add_dependency 'hashie'
   s.files = Dir['lib/**/*'] + %w(carnivore.gemspec README.md CHANGELOG.md)
 end

data/lib/carnivore/callback.rb

@@ -1,6 +1,7 @@
 require 'carnivore'
 
 module Carnivore
+  # Payload modifier
   class Callback
 
     class << self
@@ -10,15 +11,21 @@ module Carnivore
 
     include Celluloid
     include Carnivore::Utils::Logging
+    # @!parse include Carnivore::Utils::Logging
 
+    # @return [String, Symbol] name of callback
     attr_reader :name
+    # @return [Carnivore::Source] source this callback is attached
+    attr_reader :source
 
-    # name:: Name of the callback
-    # block:: Optional `Proc` to define the callback behavior
     # Creates a new callback. Optional block to define callback
     # behavior must be passed as a `Proc` instance, not a block.
-    def initialize(name, block=nil)
+    #
+    # @param name [String, Symbol] name of the callback
+    # @param block [Proc] optionally define the callback behavior
+    def initialize(name, source, block=nil)
       @name = name
+      @source = source
       if(block.nil? && self.class == Callback)
         raise ArgumentError.new 'Block is required for dynamic callbacks!'
       end
@@ -28,32 +35,41 @@ module Carnivore
 
     # Used by custom callback classes for setup
     def setup
+      debug 'No custom setup defined'
     end
 
     # Provide nice output when printed
+    #
+    # @return [String]
     def inspect
       "callback<#{self.name}:#{self.object_id}>"
     end
     alias_method :to_s, :inspect
 
-    # message:: Carnivore::Message
-    # Return true if message should be handled by this callback
+    # Message is valid for this callback
+    #
+    # @param message [Carnivore::Message]
+    # @return [TrueClass, FalseClass]
     def valid?(message)
       true
     end
 
-    # message:: Carnivore::Message
-    # Pass message to registered callbacks
+    # Execute callback against given message
+    #
+    # @param message [Carnivore::Message]
     def call(message)
-      if(valid?(message))
-        debug ">> Received message is valid for this callback (#{message})"
-        execute(message)
-      else
-        debug "Invalid message for this callback #{message})"
+      begin
+        if(valid?(message))
+          debug ">> Received message is valid for this callback (#{message})"
+          execute(message)
+        else
+          debug "Invalid message for this callback #{message})"
+        end
+      rescue => e
+        error "[callback: #{self}, source: #{message[:source]}, message: #{message[:message].object_id}]: #{e.class} - #{e}"
+        debug "#{e.class}: #{e}\n#{e.backtrace.join("\n")}"
+        nil
       end
-    rescue => e
-      error "[callback: #{self}, source: #{message[:source]}, message: #{message[:message].object_id}]: #{e.class} - #{e}"
-      debug "#{e.class}: #{e}\n#{e.backtrace.join("\n")}"
     end
 
   end

data/lib/carnivore/config.rb

@@ -3,14 +3,18 @@ require 'mixlib/config'
 require 'carnivore'
 
 module Carnivore
+  # Configuration helper
   class Config
 
     extend Mixlib::Config
 
     class << self
 
-      # v:: Boolean value
       # Set/get automatic symbolization of hash keys
+      #
+      # @param v [Object] truthy or falsey value
+      # @return [TrueClass, FalseClass]
+      # v:: Boolean value
       def auto_symbolize(v=nil)
         unless(v.nil?)
           @hash_symbolizer = !!v
@@ -18,16 +22,20 @@ module Carnivore
         @hash_symbolizer.nil? ? false : @hash_symbolizer
       end
 
-      # args:: configuration hash
       # Merge provided args into configuration
+      #
+      # @param args [Hash]
+      # @return [self]
       def configure(args)
         build(args[:config_path]) if args[:config_path]
         self.merge!(args)
         self
       end
 
-      # path_or_hash:: Path to JSON file or configuration Hash
       # Populates the configuration
+      #
+      # @param path_or_hash [String, Hash] Path to JSON file or configuration hash
+      # @return [self]
       def build(path_or_hash)
         if(path_or_hash.is_a?(Hash))
           conf = path_or_hash
@@ -45,18 +53,20 @@ module Carnivore
         self
       end
 
-      # ary: keys into a hash
-      # Returns value if exists or nil
-      #  Example:
-      #    Config.build(:my_app => {:port => 30})
-      #    Config.get(:my_app, :port) => 30
-      #    Config.get(:my_app, :host) => nil
-      #    Config.get(:other_app, :port) => nil
-      #    Config.get(:my_app, :mail, :server) => nil
+      # Fetch value from configuration
+      #
+      # @param ary [String, Symbol] list of strings or symbols as hash path
+      # @return [Object] return value or nil
+      # @example
+      #   Config.build(:my_app => {:port => 30})
+      #   Config.get(:my_app, :port) => 30
+      #   Config.get(:my_app, :host) => nil
+      #   Config.get(:other_app, :port) => nil
+      #   Config.get(:my_app, :mail, :server) => nil
       def get(*ary)
         value = Carnivore::Utils.retrieve(self, *ary)
         if(value.is_a?(Hash) && auto_symbolize)
-          Carnivore::Utils.symbolize_hash(value)
+          Smash.new(value)
         else
           value
         end

data/lib/carnivore/container.rb

@@ -2,17 +2,25 @@ require 'carnivore'
 require 'celluloid/logger'
 
 module Carnivore
+  # Module used for building isolation
   class Container < Module
 
     include Carnivore::Utils::Logging
+    # @!parse include Carnivore::Utils::Logging
 
     class << self
+
+      # @return [Celluloid::Logger]
       def log
         Celluloid::Logger
       end
+
     end
+
+    # @return [Celluloid::Logger]
     def log
       Celluloid::Logger
     end
+
   end
 end

data/lib/carnivore/errors.rb

@@ -1,7 +1,9 @@
 require 'carnivore'
 
 module Carnivore
+  # Default Carnivore error class
   class Error < StandardError
+    # Supervisor has died
     class DeadSupervisor < Error; end
   end
 end

data/lib/carnivore/message.rb

@@ -1,40 +1,47 @@
 require 'carnivore'
 
 module Carnivore
+  # Wraps a message (Hash) with Carnivore specific helpers
   class Message
 
+    # @return [Hash] underlying message hash
     attr_reader :args
 
+    # @param args [Hash]
+    # @option args [Carnivore::Source] :source origin source of message
     def initialize(args={})
+      args = args.to_smash
       unless(args[:source])
         raise ArgumentError.new("A valid `Carnivore::Source` name must be provided via `:source`")
       end
-      @args = args.dup
+      @args = args
     end
 
-    # Helper method to return keys available from `args`
+    # @return [Array<String>] keys available in message hash
     def keys
       args.keys
     end
 
-    # k:: key
-    # Accessor into message
+    # Message accessor
+    #
+    # @param k [String, Symbol]
     def [](k)
-      args[k.to_sym] || args[k.to_s]
+      args[k]
     end
 
-    # args:: Arguments
     # Confirm message was received on source
+    #
+    # @param args [Object] list passed to Carnivore::Source#confirm
     def confirm!(*args)
       self[:source].confirm(*([self] + args).flatten(1).compact)
     end
 
-    # Formatted inspection string
+    # @return [String] formatted inspection string
     def inspect
       "<Carnivore::Message[#{self.object_id}] @args=#{args.inspect}>"
     end
 
-    # String representation
+    # @return [String] string representation
     def to_s
       "<Carnivore::Message:#{self.object_id}>"
     end

data/lib/carnivore/runner.rb

@@ -1,17 +1,19 @@
-require 'carnivore/autoloader'
+require 'carnivore'
 
 module Carnivore
   class << self
 
-    # block:: Block of configuration
     # Add configuration to Carnivore
+    #
+    # @yield block of configuration
+    # @return [self]
     def configure(&block)
       mod = Container.new
       mod.instance_exec(mod, &block)
       self
     end
 
-    # Start carnivore
+    # Start the Carnivore subsystem
     def start!
       supervisor = nil
       begin
@@ -44,7 +46,9 @@ module Carnivore
         sleep 10
         retry
       rescue Exception => e
-        supervisor.terminate
+        Celluloid::Logger.warn "Exception type encountered forcing shutdown - #{e.class}: #{e}"
+        Celluloid::Logger.debug "Shutdown exception info: #{e.class}: #{e}\n#{e.backtrace.join("\n")}"
+        supervisor.terminate if supervisor
         # Gracefully shut down
       end
     end

data/lib/carnivore/source/test.rb

@@ -1,18 +1,23 @@
 module Carnivore
   class Source
+    # Test source
     class Test < Source
 
+      # Maximum rand value
       RAND_MAX = 99999
+      # Default rand divisor
       RAND_DIV = 3
+      # Sleep length when valid
       RAND_SLEEP = 10
 
-      def setup(args={})
-      end
-
+      # Note that we are connected
       def connect(*args)
         info 'Test connect called'
       end
 
+      # Receive randomly generated message
+      #
+      # @return [Array<String>]
       def receive(*args)
         if(rand(RAND_MAX) % RAND_DIV == 0)
           sleep_for = rand(RAND_SLEEP)
@@ -22,6 +27,9 @@ module Carnivore
         20.times.map{('a'..'z').to_a.shuffle.first}.join
       end
 
+      # Dummy transmit message
+      #
+      # @param message [Carnivore::Message]
       def transmit(message)
         info "Transmit requested: #{message}"
       end