krakow 0.2.2 → 0.3.0

data/lib/krakow/distribution.rb

@@ -1,4 +1,8 @@
+require 'krakow'
+
 module Krakow
+  # Message distribution
+  # @abstract
   class Distribution
 
     autoload :Default, 'krakow/distribution/default'
@@ -7,110 +11,147 @@ module Krakow
 
     include Celluloid
     include Utils::Lazy
+    # @!parse include Krakow::Utils::Lazy::InstanceMethods
+    # @!parse extend Krakow::Utils::Lazy::ClassMethods
+
+    attr_accessor :ideal, :flight_record, :registry
+
+    # @!group Attributes
 
-    attr_accessor :max_in_flight, :ideal, :flight_record, :registry
+    # @!macro [attach] attribute
+    #   @!method $1
+    #     @return [$2] the $1 $0
+    #   @!method $1?
+    #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+    attribute :consumer, Krakow::Consumer, :required => true
+    attribute :watch_dog_interval, Numeric, :default => 1.0
+    attribute :backoff_interval, Numeric
+    attribute :max_in_flight, Integer, :default => 1
+
+    # @!endgroup
 
     def initialize(args={})
       super
-      optional :watch_dog_interval, :backoff_interval
-      arguments[:watch_dog_interval] ||= 5
-      @max_in_flight = arguments[:max_in_flight] || 1
       @ideal = 0
       @flight_record = {}
       @registry = {}
     end
 
-    # Reset flight distributions
+    # [Abstract] Reset flight distributions
     def redistribute!
       raise NotImplementedError.new 'Custom `#redistrubute!` method must be provided!'
     end
 
-    # connection:: Connection
-    # Determine RDY value for given connection
-    def calculate_ready!(connection)
+    # [Abstract] Determine RDY value for given connection
+    # @param connection_identifier [String]
+    # @return [Integer]
+    def calculate_ready!(connection_identifier)
       raise NotImplementedError.new 'Custom `#calculate_ready!` method must be provided!'
     end
 
-    # message:: FrameType::Message or message ID string
-    # Remove message metadata from registry. Should be used after
-    # confirmations or requeue.
+    # Remove message metadata from registry
+    #
+    # @param message [Krakow::FrameType::Message, String] message or ID
+    # @return [Krakow::Connection]
     def unregister_message(message)
       msg_id = message.respond_to?(:message_id) ? message.message_id : message.to_s
-      connection = flight_record[msg_id]
-      registry_info = registry_lookup(connection)
+      connection = connection_lookup(flight_record[msg_id])
+      registry_info = registry_lookup(connection.identifier)
       flight_record.delete(msg_id)
       registry_info[:in_flight] -= 1
-      calculate_ready!(connection)
+      calculate_ready!(connection.identifier)
       connection
     end
 
-    # connection:: Connection
     # Return the currently configured RDY value for given connnection
-    def ready_for(connection)
-      registry_lookup(connection)[:ready]
+    #
+    # @param connection_identifier [String]
+    # @return [Integer]
+    def ready_for(connection_identifier)
+      registry_lookup(connection_identifier)[:ready]
     end
 
-    # connection:: Connection
+
     # Send RDY for given connection
+    #
+    # @param connection [Krakow::Connection]
+    # @return [Krakow::FrameType::Error,nil]
     def set_ready_for(connection, *_)
       connection.transmit(
         Command::Rdy.new(
-          :count => ready_for(connection)
+          :count => ready_for(connection.identifier)
         )
       )
     end
 
     # Initial ready value used for new connections
+    #
+    # @return [Integer]
     def initial_ready
       ideal > 0 ? 1 : 0
     end
 
-    # message:: FrameType::Message
-    # connection:: Connection
     # Registers message into registry and configures for distribution
-    def register_message(message, connection)
-      registry_info = registry_lookup(connection)
+    #
+    # @param message [FrameType::Message]
+    # @param connection_identifier [String]
+    # @return [Integer]
+    def register_message(message, connection_identifier)
+      registry_info = registry_lookup(connection_identifier)
       registry_info[:in_flight] += 1
-      flight_record[message.message_id] = connection_key(connection)
-      calculate_ready!(connection)
+      flight_record[message.message_id] = connection_identifier
+      calculate_ready!(connection_identifier)
     end
 
-    # connection:: Connection
     # Add connection to make available for RDY distribution
+    #
+    # @param connection [Krakow::Connection]
+    # @return [TrueClass]
     def add_connection(connection)
-      registry[connection_key(connection)] = {
-        :ready => initial_ready,
-        :in_flight => 0,
-        :failures => 0,
-        :backoff_until => 0
-      }
+      unless(registry[connection.identifier])
+        registry[connection.identifier] = {
+          :ready => initial_ready,
+          :in_flight => 0,
+          :failures => 0,
+          :backoff_until => 0
+        }
+      end
       true
     end
 
-    # connection:: Connection
     # Remove connection from RDY distribution
-    def remove_connection(connection)
+    #
+    # @param connection_identifier [String]
+    # @return [TrueClass]
+    def remove_connection(connection_identifier, *args)
       # remove connection from registry
-      registry.delete(connection_key(connection))
+      registry.delete(connection_identifier)
       # remove any in flight messages
       flight_record.delete_if do |k,v|
-        v == connection_key(connection)
+        if(k == connection_identifier)
+          warn "Removing in flight reference due to failed connection: #{k}"
+          true
+        end
       end
       true
     end
 
-    # connection:: Connection
-    # Return lookup key (actor reference)
-    def connection_key(connection)
-      connection
+    # Return connection associated with given registry key
+    #
+    # @param identifier [String] connection identifier
+    # @return [Krakow::Connection, nil]
+    def connection_lookup(identifier)
+      consumer.connection(identifier)
     end
 
-    # msg_id:: Message ID string
-    # Return source connection of given `msg_id`. If block is
-    # provided, the connection instance will be yielded to the block
-    # and the result returned.
+    # Return source connection for given message ID
+    #
+    # @param msg_id [String]
+    # @yield execute with connection
+    # @yieldparam connection [Krakow::Connection]
+    # @return [Krakow::Connection, Object]
     def in_flight_lookup(msg_id)
-      connection = flight_record[msg_id]
+      connection = connection_lookup(flight_record[msg_id])
       unless(connection)
         abort Krakow::Error::LookupFailed.new("Failed to locate in flight message (ID: #{msg_id})")
       end
@@ -121,34 +162,42 @@ module Krakow
       end
     end
 
-    # connection:: Connection
     # Return registry information for given connection
-    def registry_lookup(connection)
-      registry[connection_key(connection)] ||
-        abort(Krakow::Error::LookupFailed.new("Failed to locate connection information in registry (#{connection})"))
+    # @param connection_identifier [String]
+    # @return [Hash] registry information
+    # @raise [Krakow::Error::LookupFailed]
+    def registry_lookup(connection_identifier)
+      registry[connection_identifier] ||
+        abort(Krakow::Error::LookupFailed.new("Failed to locate connection information in registry (#{connection_identifier})"))
     end
 
-    # Return list of all connections in registry
+    # @return [Array<Krakow::Connection>] connections in registry
     def connections
-      registry.keys
+      registry.keys.map do |identifier|
+        connection_lookup(identifier)
+      end.compact
     end
 
-    # connection:: Connection
     # Log failure of processed message
-    def failure(connection)
+    #
+    # @param connection_identifier [String]
+    # @return [TrueClass]
+    def failure(connection_identifier)
       if(backoff_interval)
-        registry_info = registry_lookup(connection)
+        registry_info = registry_lookup(connection_identifier)
         registry_info[:failures] += 1
         registry_info[:backoff_until] = Time.now.to_i + (registry_info[:failures] * backoff_interval)
       end
       true
     end
 
-    # connection:: Connection
     # Log success of processed message
-    def success(connection)
+    #
+    # @param connection_identifier [String]
+    # @return [TrueClass]
+    def success(connection_identifier)
       if(backoff_interval)
-        registry_info = registry_lookup(connection)
+        registry_info = registry_lookup(connection_identifier)
         if(registry_info[:failures] > 1)
           registry_info[:failures] -= 1
           registry_info[:backoff_until] = Time.now.to_i + (registry_info[:failures] * backoff_interval)
@@ -156,6 +205,7 @@ module Krakow
           registry_info[:failures] = 0
         end
       end
+      true
     end
 
   end

data/lib/krakow/exceptions.rb

@@ -1,13 +1,27 @@
+require 'krakow'
+
 module Krakow
+  # Base error type
   class Error < StandardError
 
+    # Failed to enable required feature on connection
     class ConnectionFeatureFailure < Error; end
+    # Failed to perform lookup (not found)
     class LookupFailed < Error; end
+    # Connection has failed
     class ConnectionFailure < Error; end
+    # Configuration is not in valid state
     class ConfigurationError < Error; end
+    # Connection is temporarily unavailable
+    class ConnectionUnavailable < Error; end
+    # Consumer was not set
+    class OriginNotFound < Error; end
 
+    # Invalid response
     class BadResponse < Error
+      # @return [Response] error response
       attr_accessor :result
+      # No response received
       class NoResponse < BadResponse
       end
     end

data/lib/krakow/frame_type/error.rb

@@ -1,16 +1,22 @@
+require 'krakow'
+
 module Krakow
   class FrameType
+    # Error from server
     class Error < FrameType
 
-      def initialize(args={})
-        super
-        required! :error
-      end
+      # @!group Attributes
 
-      def error
-        arguments[:error]
-      end
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :error, String, :required => true
+
+      # @!endgroup
 
+      # @return [String] content of error
       def content
         error
       end

data/lib/krakow/frame_type/message.rb

@@ -1,16 +1,59 @@
+require 'krakow'
+
 module Krakow
   class FrameType
+    # Message received from server
     class Message < FrameType
 
-      def initialize(args={})
-        super
-        required! :attempts, :timestamp, :message_id, :message
-      end
+      # @return [Krakow::Consumer]
+      attr_accessor :origin
+
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :attempts, Integer, :required => true
+      attribute :timestamp, Integer, :required => true
+      attribute :message_id, String, :required => true
+      attribute :message, String, :required => true
 
+      # @!endgroup
+
+      # Message content
+      #
+      # @return [String]
       def content
         message
       end
 
+      # @return [Krakow::Consumer]
+      def origin
+        unless(@origin)
+          error 'No origin has been specified for this message'
+          abort Krakow::Error::OriginNotFound.new('No origin specified for this message')
+        end
+        @origin
+      end
+
+      # Proxy to [Krakow::Consumer#confirm]
+      def confirm(*args)
+        origin.confirm(*[self, *args].compact)
+      end
+      alias_method :finish, :confirm
+
+      # Proxy to [Krakow::Consumer#requeue]
+      def requeue(*args)
+        origin.requeue(*[self, *args].compact)
+      end
+
+      # Proxy to [Krakow::Consumer#touch]
+      def touch(*args)
+        origin.touch(*[self, *args].compact)
+      end
+
     end
   end
 end

data/lib/krakow/frame_type/response.rb

@@ -1,12 +1,22 @@
+require 'krakow'
+
 module Krakow
   class FrameType
+    # Response from server
     class Response < FrameType
 
-      def initialize(args={})
-        super
-        required! :response
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :response, String, :required => true
+
+      # @!endgroup
 
+      # @return [String] content of response
       def content
         response
       end

data/lib/krakow/frame_type.rb

@@ -1,4 +1,8 @@
+require 'krakow'
+
 module Krakow
+  # Received message
+  # @abstract
   class FrameType
 
     autoload :Error, 'krakow/frame_type/error'
@@ -6,25 +10,34 @@ module Krakow
     autoload :Response, 'krakow/frame_type/response'
 
     include Utils::Lazy
+    # @!parse include Krakow::Utils::Lazy::InstanceMethods
+    # @!parse extend Krakow::Utils::Lazy::ClassMethods
 
+    # Registered frame types
     FRAME_TYPE_MAP = [
       FrameType::Response,
       FrameType::Error,
       FrameType::Message
     ]
+    # Size bytes
     SIZE_BYTES = 4
 
     class << self
 
-      # bytes:: 8 bytes
-      # Return information about incoming frame
+      # Information about incoming frame
+      # @param bytes [String]
+      # @return [Hash]
       def decode(bytes)
         size, type = bytes.unpack('l>l>')
         {:size => size - SIZE_BYTES, :type => type}
       end
 
-      # args:: arguments (:type, :data, :size)
       # Build proper FrameType instance based on args
+      # @param args [Hash]
+      # @option args [FrameType] :type class of frame
+      # @option args [String] :data
+      # @option args [Integer] :size
+      # @return [FrameType]
       def build(args={})
         klass = FRAME_TYPE_MAP[args[:type].to_i]
         if(klass == FrameType::Response)
@@ -42,12 +55,11 @@ module Krakow
       end
     end
 
-    def initialize(args={})
-      super
-    end
-
+    # Content of message
+    #
+    # @return [String]
     def content
-      raise NoMethodError.new 'Content method not properly defined!'
+      raise NotImplementedError.new 'Content method not properly defined!'
     end
 
   end

data/lib/krakow/producer/http.rb

@@ -2,35 +2,85 @@ require 'http'
 require 'uri'
 require 'ostruct'
 
+require 'cgi'
+# NOTE: Prevents weird "first" run behavior
+begin
+  require 'json'
+rescue LoadError
+  # ignore (maybe log?)
+end
+
+require 'krakow'
+
 module Krakow
   class Producer
+
+    # HTTP based producer
     class Http
 
+      include Utils::Lazy
+      # @!parse include Krakow::Utils::Lazy::InstanceMethods
+      # @!parse extend Krakow::Utils::Lazy::ClassMethods
+
+      # Wrapper for HTTP response hash
       class Response < OpenStruct
       end
 
-      include Utils::Lazy
-
       attr_reader :uri
 
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :endpoint, String, :required => true
+      attribute :topic, String, :required => true
+      attribute :config, Hash, :default => ->{ Hash.new }
+      attribute :ssl_context, Hash
+
+      # @!endgroup
+
       def initialize(args={})
         super
-        required! :endpoint, :topic
+        build_ssl_context if ssl_context
         @uri = URI.parse(endpoint)
       end
 
+      # Create a new SSL context
+      #
+      # @return [OpenSSL::SSL::SSLContext]
+      def build_ssl_context
+        require 'openssl'
+        context = OpenSSL::SSL::SSLContext.new
+        context.cert = OpenSSL::X509::Certificate.new(File.open(ssl_context[:certificate]))
+        context.key = OpenSSL::PKey::RSA.new(File.open(ssl_context[:key]))
+        config[:ssl_context] = context
+      end
+
+      # Send a message via HTTP
+      #
+      # @param method [String, Symbol] HTTP method to use (:get, :put, etc)
+      # @param path [String] URI path
+      # @param args [Hash] payload hash
+      # @return [Response]
       def send_message(method, path, args={})
         build = uri.dup
         build.path = "/#{path}"
-        response = HTTP.send(method, build.to_s, args)
+        response = HTTP.send(method, build.to_s, args.merge(config))
         begin
-          response = MultiJson.load(response.response.body)
+          response = MultiJson.load(response.body.to_s)
         rescue MultiJson::LoadError
-          response = {'status_code' => response == 'OK' ? 200 : nil, 'status_txt' => response, 'data' => nil}
+          response = {'status_code' => response.code, 'status_txt' => response.body.to_s, 'data' => nil}
         end
         Response.new(response)
       end
 
+      # Send messages
+      #
+      # @param payload [String] message
+      # @return [Response]
       def write(*payload)
         if(payload.size == 1)
           payload = payload.first
@@ -46,18 +96,28 @@ module Krakow
         end
       end
 
+      # Create the topic
+      #
+      # @return [Response]
       def create_topic
         send_message(:post, :create_topic,
           :params => {:topic => topic}
         )
       end
 
+      # Delete the topic
+      #
+      # @return [Response]
       def delete_topic
         send_message(:post, :delete_topic,
           :params => {:topic => topic}
         )
       end
 
+      # Create channel on topic
+      #
+      # @param chan [String] channel name
+      # @return [Response]
       def create_channel(chan)
         send_message(:post, :create_channel,
           :params => {
@@ -67,6 +127,10 @@ module Krakow
         )
       end
 
+      # Delete channel on topic
+      #
+      # @param chan [String] channel name
+      # @return [Response]
       def delete_channel(chan)
         send_message(:post, :delete_channel,
           :params => {
@@ -76,12 +140,19 @@ module Krakow
         )
       end
 
+      # Remove all messages from topic
+      #
+      # @return [Response]
       def empty_topic
         send_message(:post, :empty_topic,
           :params => {:topic => topic}
         )
       end
 
+      # Remove all messages from given channel on topic
+      #
+      # @param chan [String] channel name
+      # @return [Response]
       def empty_channel(chan)
         send_message(:post, :empty_channel,
           :params => {
@@ -91,6 +162,10 @@ module Krakow
         )
       end
 
+      # Pause messages on given channel
+      #
+      # @param chan [String] channel name
+      # @return [Response]
       def pause_channel(chan)
         send_message(:post, :pause_channel,
           :params => {
@@ -100,6 +175,10 @@ module Krakow
         )
       end
 
+      # Resume messages on a given channel
+      #
+      # @param chan [String] channel name
+      # @return [Response]
       def unpause_channel(chan)
         send_message(:post, :unpause_channel,
           :params => {
@@ -109,6 +188,10 @@ module Krakow
         )
       end
 
+      # Server stats
+      #
+      # @param format [String] format of data
+      # @return [Response]
       def stats(format='json')
         send_message(:get, :stats,
           :params => {
@@ -117,10 +200,16 @@ module Krakow
         )
       end
 
+      # Ping the server
+      #
+      # @return [Response]
       def ping
         send_message(:get, :ping)
       end
 
+      # Server information
+      #
+      # @return [Response]
       def info
         send_message(:get, :info)
       end