haredo 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1585745834668ad5a1db7ceade69f55cad742453
-  data.tar.gz: adf26761a2a995d47f3e3d7d5c11453fc78b65cd
+  metadata.gz: 85222fb487a3ac64174d10d323211ba37ddf427b
+  data.tar.gz: 758c7117f150c96b882132d14d38e2e0495ea080
 SHA512:
-  metadata.gz: 20b36a13ae81dc1c33636d786da3c3248e3071faf9d5a55cede56b9c63ba7bf9165be0d2f13d0cc2e3d32126c2f6c5cb53e6109eb41dd74b9195003cbc895141
-  data.tar.gz: dbe8eff27818b3ef38fa3687bfc20df928ba4e2e88edc85c7c789c0eeef4b7e8d1ec8b34cf03315c8d806ae8eb43c261943df9134b51d6ac31463c11f04c4d1b
+  metadata.gz: ac949da33da127bdf7b1b587c346349a5abdb8e5ccf30c4bc18c57613fa1729c50b2776bad73357ae3852f326e906870daecacacc745ed0006f42f4bab6f9141
+  data.tar.gz: 2a5d9416907828acbcdf9d6a4e8259b56b06d82025eb4901e2acecbd39488a41f0ef4a32af4b20258c54e45b8ab17e3503fe56d9da8e0f10681d83e3e3987f83

data/README.md

@@ -2,22 +2,31 @@
 
 ## About
 
-An easy-to-use framework for quickly creating client/server applications in Ruby
-over RabbitMQ. The RabbitMQ terminology uses metaophors of publishers and
-consumers. This framework -- which is a very thin wrapper on top of
-[Bunny](http://rubybunny.info/) -- slightly modifies the semantics and provides
-an intuitive framework for easily and quickly implementing network services and
-clients to use them.
+This is an easy-to-use framework for creating peer-to-peer applications in Ruby
+via [RabbitMQ](http://www.rabbitmq.com/). While RabbitMQ is a robust, feature
+rich message broker, it (like all AMQP message brokers) uses a somewhat complex
+terminology that can be a little bewildering to to newcomers of AMQP.
+
+This gem -- built atop the [Bunny AMQP client](http://rubybunny.info/) -- uses a
+small subset of RabbitMQ's capabilities to provide an intuitive client/server
+framework for easily and quickly implementing network services and simple peer
+to peer applications. It specifically designed for those who are not familiar
+with the ins and outs of the AMQP protocol.
 
 ## How It Works
 
-Here is a complete example -- the following plugin/program (included in
-<tt>src/examples/service.rb</tt>) create a simple network service that takes a
-number and add one, along with a client that uses it:
+Here is a complete example -- the following program creates a simple network
+service that takes a number and add one, along with a client that uses it. They
+both run simultaneously in the same script.
 
 ```ruby
 #!/usr/bin/env ruby
 
+$rabbitmq_host     = 'localhost'
+$rabbitmq_username = 'guest'
+$rabbitmq_password = 'guest'
+$haredo_test_queue = 'HareDo'
+
 # Simple service
 class Service < HareDo::Service
 
@@ -27,11 +36,8 @@ class Service < HareDo::Service
   end
 
   def serve(msg)
-    headers  = msg.properties.headers
-    reply_to = msg.properties.reply_to
-
-    data = headers['i'].to_i + 1
-    send(reply_to, data.to_s, { :rc => 1 })
+    data = msg.headers['i'].to_i + 1
+    send(msg.properties.reply_to, :data => data.to_s)
   end
 
 end # class Server
@@ -49,10 +55,10 @@ client = HareDo::Client.new()
 client.connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
 service = Service.new($haredo_test_queue)
 
-service.run(false)
+service.run(:blocking => false)
 
 1.upto(10) do |i|
-  client.send($haredo_test_queue, 'data', { :i => i })
+  client.send($haredo_test_queue, :headers => { :i => i })
   msg = @client.receive()
 
   dump_message msg
@@ -61,9 +67,166 @@ service.run(false)
 end
 ```
 
-The server runs in non-blocking mode. The client makes 10 calls sending 10
-monotonically increasing integer values, waits for the response (using a
-blocking timeout) after each call and checks the results.
+The service takes a single argument -- the queue name. This is like an email
+address or an IP address. It's an identifier you use to direct messages to the
+service.
+
+The client sends 10 messages to the service, each containing monotonically
+increasing integer values. It waits for the response (using a blocking timeout)
+after each call and checks the results.
+
+### Request/Response Pattern
+
+While it is not required that a service reply, the requests/response pattern is
+the main function of this library. We are often interested in sending a request
+and getting one (or more responses) back. Implementing this is only a slight
+change from the above example. The following implements a service that responds
+with a single message.
+
+The server code is as follows:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'haredo/peer'
+
+$rabbitmq_host     = 'localhost'
+$rabbitmq_username = 'guest'
+$rabbitmq_password = 'guest'
+$haredo_test_queue = 'HareDo'
+
+class Service < HareDo::Service
+
+  def initialize(name)
+    super
+    connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
+  end
+
+  def serve(msg)
+    reply(msg, :data => 'Reply')
+  end
+end
+
+Service.new($haredo_test_queue).run()
+```
+
+The client code is a follows:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'haredo/peer'
+
+$rabbitmq_host     = 'localhost'
+$rabbitmq_username = 'guest'
+$rabbitmq_password = 'guest'
+$haredo_test_queue = 'HareDo'
+
+client = HareDo::Client.new()
+client.connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
+response = @client.call($haredo_test_queue, :data => 'jujifruit')
+```
+
+You can run both in the same script by setting the service code to non-blocking
+(passing <tt>:blocking => false</tt> to the <tt>Service::run()</tt> method):
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'haredo/peer'
+
+$rabbitmq_host     = 'localhost'
+$rabbitmq_username = 'guest'
+$rabbitmq_password = 'guest'
+$haredo_test_queue = 'HareDo'
+
+class Service < HareDo::Service
+
+  def initialize(name)
+    super
+    connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
+  end
+
+  def serve(msg)
+    reply(msg, :data => 'Reply')
+  end
+end
+
+service = Service.new($haredo_test_queue)
+service.run(:blocking => false)
+
+client = HareDo::Client.new()
+client.connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
+response = @client.call($haredo_test_queue, :data => 'jujifruit')
+```
+
+The client uses the <tt>call()</tt> method to send a message and wait for a
+response. This is just a convenience method that wraps <tt>send()</tt> and
+<tt>receive()</tt>. Interally, a unique message ID is assigned to the request
+message, and the service will send back a reply with the message ID set in the
+message headers.
+
+The client will block waiting for the reponse -- up to <tt>client.timeout</tt>
+seconds (floating point value). The default is 1 second. You can change this to
+whatever value you like. If a timeout occurs, the <tt>call()</tt> will return
+<tt>nil</tt>. Subsequent calls will fail to get the response, even if it comes
+in later (it will be discarded).
+
+The service uses the <tt>reply()</tt> method rather than the <tt>send()</tt>
+method to return a response. This method takes the original request message,
+extracts the <tt>to</tt> address along with message ID and addresses a message
+back to the client. It adds a header value of <tt>reply=true</tt>. This lets the
+client know that the message coming in is a reply. It needs this because what if
+another peer sent it a message with the same message id? It might interpret that
+message as the reply from the service. Therefore this flag lets the client know
+that the message is a reply to a previous request.
+
+Using this simple pattern, you can easily create heterogeneous network services
+in just a few lines of code.
+
+### Roud-Robin Services
+
+Say you want to scale your service to three nodes distributed across three
+different machines. The only thing you need to do differently is redefine one
+method -- <tt>Service::createQueue()</tt>. The following is updates the above
+example and makes is available to run in this way:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'haredo/peer'
+
+$rabbitmq_host     = 'localhost'
+$rabbitmq_username = 'guest'
+$rabbitmq_password = 'guest'
+$haredo_test_queue = 'HareDo'
+
+class Service < HareDo::Service
+
+  def initialize(name)
+    super
+    connect($rabbitmq_username, $rabbitmq_password, $rabbitmq_host)
+  end
+
+  def createQueue()
+    return @channel.queue(@queue_name, :auto_delete => true)
+  end   
+
+
+  def serve(msg)
+    reply(msg, :data => 'Reply')
+  end
+end
+
+Service.new($haredo_test_queue).run()
+```
+
+The only thing we did is remove the <tt>exclusive</tt> attribute which is by
+default in the <tt>HareDO::Service</tt> base class. By making the queue this
+services uses non-exclusive, mulitple service instances can now connect and
+process requests. RabbitMQ will automatically distribute messages equally across
+all the running services, dividing up the load. You can now scale your service
+to as many machines and processes as you like.
 
 ## Installation
 

data/src/lib/haredo/peer.rb

@@ -3,18 +3,35 @@ require 'haredo/version'
 
 module HareDo
 
+# This is a simple class that represents a message delivered from a queue. The
+# attributes are as follows:
+#
+#  * @info member contains the delivery information
+#  * @properties contains the message properties
+#  * @headers the message headers
+#  * @data the message data
+
 class Message
 
-  attr_reader :info, :properties, :data
+  attr_reader :info, :properties, :headers, :data
 
   def initialize(info=nil, properties=nil, data=nil)
     @info       = info
     @properties = properties
-    @data       = data
+
+    if properties
+      @headers = properties[:headers]
+    else
+      @headers = {}
+    end
+
+    @data = data
   end
 
 end
 
+# This is an abstract base class used for both Client and Service.
+
 class Node
 
   attr_reader :queue
@@ -23,40 +40,80 @@ class Node
     
   end
 
+  # Connect to RabbitMQ
+  #
+  # @param user The RabbitMQ username
+  # @param password The RabbitMQ password
+  # @param host The RabbitMQ host
+  # @param port The RabbitMQ port
+  # @return Returns true if connection was successful, false othewise.
+
   def connect(user, password, host='localhost', port='5672')
-    @cnx = Bunny.new("amqp://#{user}:#{password}@#{host}:#{port}")
 
-    @cnx.start()
+    begin
+      @cnx = Bunny.new("amqp://#{user}:#{password}@#{host}:#{port}")
+      @cnx.start()
+    rescue Bunny::TCPConnectionFailed => e
+      return false
+    end
 
     @channel  = @cnx.create_channel()
 
     return true
   end
 
+  # Disconnect from RabbitMQ
   def disconnect()
     @cnx.close()
   end
 
-  def send(to, data, headers = {}, from=nil)
+  # Sends a message.
+  # @param to The to address
+  # @param :data Message data
+  # @param :headers Message headers
+  # @param :headers Message from address
+  # @param :properties Message properties
+
+  def send(to, args)
+
+    data       = args[:data]
+    from       = args[:from]
+    headers    = args[:headers]    || {}
+    properties = args[:properties] || {}
 
-    if from.nil?
-      from = @queue.name if @queue
+    properties[:routing_key] = to
+    properties[:headers]     = headers
+
+    if not from.nil?
+      properties[:reply_to] = from 
+    else
+      properties[:reply_to] = @queue.name if @queue
     end
 
-    @exchange.publish( data, 
-                       :routing_key => to, 
-                       :headers     => headers,
-                       :reply_to    => from )
+    properties[:message_id] = @mid
+
+    @exchange.publish(data, properties) 
   end
 
 end # class Node
 
+# Implements a basic client designed for sending messages asynchronously and
+# blocking while receiving replies.
+
 class Client < Node
 
   attr_reader :queue
+  attr_accessor :timeout, :sleep_interval
 
   def initialize()
     super
+
+    @timeout        = 1.0
+    @sleep_interval = 0.001
+    @receive_queue  = {}
+
+    # Message identifier
+    @mid = 0
   end
 
   def connect(user, password, host='localhost', port='5672')
@@ -68,31 +125,114 @@ class Client < Node
     @exchange = @channel.default_exchange()
   end
 
+  # Disconnect from RabbitMQ
   def disconnect()
     @queue.delete() if @queue
     super
   end
 
-  def receive(timeout = 1.0)
-    now = Time::now.to_f
+  # Sends a message. Adds the @mid as message_id in message properties.
+  # @param to The to address
+  # @param :data Message data
+  # @param :headers Message headers
+  # @param :headers Message from address
+  # @param :properties Message properties
+  #
+  # @return Returns the message ID of sent message
+
+  def send(to, args)
+
+    data       = args[:data]
+    from       = args[:from]
+    headers    = args[:headers]    || {}
+    properties = args[:properties] || {}
+
+    properties[:message_id] = @mid
+
+    super to, :data => data, :headers => headers, :properties => properties, :from => from
+
+    rc = @mid
+    @mid += 1
+
+    return rc
+  end
 
+  # Sends a message and waits for response
+  #
+  # @param to The to address
+  # @param :data Message data
+  # @param :headers Message headers
+  # @param :headers Message from address
+  # @param :properties Message properties
+  #
+  # @return Returns the response message if successful, nil otherwise. Will
+  # block until @timeout seconds elapse. Sleeps in busywait. Sleep interval is
+  # given by @sleep_interval.
+
+  def call(to, data: '', headers: {}, properties: {}, from: nil)
+    # Get message id of sent message
+    id = send(to, data: data, headers: headers, properties: properties, from: from)
+
+    # Put blank entry in queue to indicate we are expecting a response with that
+    # message id.
+    @receive_queue[id] = nil
+
+    return receive(id)
+  end
+
+  def receive(mid=nil)
+
+    if mid != nil
+      if @receive_queue.has_key?(mid)
+        msg = @receive_queue[mid]
+
+        if msg != nil
+          @receive_queue.delete(mid)        
+          return msg
+        end
+      end
+    end
+
+    now = Time::now.to_f
+    
     while true
       delivery_info, properties, payload = @queue.pop()
       
       if delivery_info != nil
-        return Message.new(delivery_info, properties, payload)
+        msg = Message.new(delivery_info, properties, payload)
+        
+        if msg.headers.has_key?('id')
+          if mid != nil 
+            if msg.headers['id'] == mid
+              # Reply flag must be set
+              if msg.headers['reply'] == 1
+                return msg
+              end
+            end
+          end
+          
+          # Only add to receive queue if we are expecting it
+          if @receive_queue.has_key?
+            @receive_queue[msg.headers['id']] = msg
+          end
+        end
       end
-      
-      if (Time::now.to_f - now) > timeout
-        return Message.new()
+
+      if (Time::now.to_f - now) > @timeout
+        # Delete entry from receive queue
+        @receive_queue.delete mid
+
+        return nil
       end
       
-      sleep 0.001
+      sleep @sleep_interval
     end    
   end
 
 end # class Client
 
+# Represents a basic service class.
+
 class Service < Node
 
   def initialize(name)
@@ -101,19 +241,50 @@ class Service < Node
     @queue_name = name
   end
 
+  # Defined the queue this service will listen on. Assumes a single-instance
+  # service therefore declares queue as exclusive.
   def createQueue()
     return @channel.queue(@queue_name, :auto_delete => true, :exclusive => true)
   end
 
-  def run(block = true)
+  # Causes the service to listen for incoming messages.
+  #
+  # @param :blocking If this is set to true, will go into indefinite blocking
+  # loop processing incoming messages.
+
+  # @returns Returns nil if non-blocking. Never returns if blocking.
+
+  def run(args)
     @queue    = createQueue()
     @exchange = @channel.default_exchange()
 
+    block = args[:blocking] || false
+
     queue.subscribe(:block => block) do |info, props, data|
       serve Message.new(info, props, data)
     end
   end
 
+  # You should use this method to reply back to a peer. It sets the reply header
+  # which tells the remote that this message is a response (as opposed to a
+  # message originating from another source which just happens to have the same
+  # message_id).
+  def reply(msg, args)
+
+    data    = args[:data]
+    headers = args[:headers] || {}
+
+    id = msg.properties.message_id.to_i
+    to = msg.properties.reply_to
+
+    # Set the reply flag to indicate that this is a response to a message
+    # sent. The message_id should already be set in the headers.
+    headers[:reply] = 1
+    headers[:id]    = id.to_i
+    
+    send(to, :headers => headers, :data => data)
+  end
+
 end # class Service
 
 end # module HareDo

data/src/lib/haredo/version.rb

@@ -1,5 +1,5 @@
 module HareDo
 
-VERSION = '0.0.1-1'
+VERSION = '0.0.2-1'
 
 end # module HareDo

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haredo
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Mike Owens
@@ -9,7 +9,21 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2013-09-19 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bunny
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email: mikeowens@gmail.com
 executables: []