rjr 0.12.2 → 0.15.1

data/lib/rjr/message.rb

@@ -2,24 +2,19 @@
 #
 # Representations of json-rpc messages in accordance with the standard
 #
-# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
 # establish client connection w/ specified args and invoke block w/ 
 # newly created client, returning it after block terminates
 
 require 'json'
+require 'rjr/common'
 
 module RJR
 
 # Message sent from client to server to invoke a json-rpc method
 class RequestMessage
-  # Helper method to generate a random id
-  def self.gen_uuid
-    ["%02x"*4, "%02x"*2, "%02x"*2, "%02x"*2, "%02x"*6].join("-") %
-        Array.new(16) {|x| rand(0xff) }
-  end
-
   # Message string received from the source
   attr_accessor :json_message
 
@@ -51,8 +46,8 @@ class RequestMessage
   def initialize(args = {})
     if args.has_key?(:message)
       begin
-        request = JSON.parse(args[:message])
         @json_message = args[:message]
+        request = JSON.parse(@json_message)
         @jr_method = request['method']
         @jr_args   = request['params']
         @msg_id    = request['id']
@@ -71,7 +66,7 @@ class RequestMessage
       @jr_method = args[:method]
       @jr_args   = args[:args]
       @headers   = args[:headers]
-      @msg_id    = RequestMessage.gen_uuid
+      @msg_id    = gen_uuid
 
     end
   end
@@ -132,8 +127,8 @@ class ResponseMessage
   # @option args [RJR::Result] :result result of json-rpc method invocation
   def initialize(args = {})
     if args.has_key?(:message)
-      response = JSON.parse(args[:message])
       @json_message  = args[:message]
+      response = JSON.parse(@json_message)
       @msg_id  = response['id']
       @result   = Result.new
       @result.success   = response.has_key?('result')
@@ -235,8 +230,8 @@ class NotificationMessage
   def initialize(args = {})
     if args.has_key?(:message)
       begin
-        notification = JSON.parse(args[:message])
         @json_message = args[:message]
+        notification = JSON.parse(@json_message)
         @jr_method = notification['method']
         @jr_args   = notification['params']
         @headers   = args.has_key?(:headers) ? {}.merge!(args[:headers]) : {}
@@ -295,7 +290,7 @@ class MessageUtil
   # to the issue of multiple messages appearing in one tcp data packet.
   #
   # TODO efficiency can probably be optimized
-  #   in the case closing '}' hasn't arrived yet
+  # in the case closing '}' hasn't arrived yet
   def self.retrieve_json(data) 
     return nil if data.nil? || data.empty?
     start  = 0
@@ -318,6 +313,42 @@ class MessageUtil
     return data[start..mi], data[(mi+1)..-1]
   end
 
+  # Mechanism to register / retrieve preformatted message
+  #
+  # @param [Symbol] id id of message to get / set
+  # @param [String] msg optional preformatted message to store
+  # @return [String] json rpc message
+  def self.message(id, msg=nil)
+    @rjr_messages ||= {}
+    @rjr_messages[id] = msg unless msg.nil?
+    @rjr_messages[id]
+  end
+
+  # Clear preformatted messages
+  def self.clear
+    @rjr_messages = {}
+  end
+
+  # Return random message from registry.
+  #
+  # Optionally specify the transport which the message must accept
+  #   (TODO turn this into a generic selection callback)
+  def self.rand_msg(transport = nil)
+    @rjr_messages ||= {}
+    messages = @rjr_messages.select { |mid,m| m[:transports].nil? || transport.nil? ||
+                                              m[:transports].include?(transport) }
+    messages[messages.keys[rand(messages.keys.size)]]
+  end
+
+end # MessageUtil
+
+# Module providing helper methods for messages
+module MessageMixins
+
+  # Wrapper around MessageUtil.message
+  def define_message(name, &bl)
+    MessageUtil.message(name, bl.call)
+  end
 end
 
 end

data/lib/rjr/node.rb

@@ -1,36 +1,38 @@
-# RJR Node
+# RJR Base Node Interface
 #
-# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
-# establish client connection w/ specified args and invoke block w/ 
-# newly created client, returning it after block terminates
-
-require 'eventmachine'
+require 'thread'
+require 'socket'
+require 'rjr/common'
+require 'rjr/message'
+require 'rjr/dispatcher'
 require 'rjr/em_adapter'
-require 'rjr/thread_pool2'
+require 'rjr/thread_pool'
 
 module RJR
 
-# Base RJR Node interface. Nodes are the central transport mechanism of rjr,
+# Base RJR Node interface. Nodes are the central transport mechanism of RJR,
 # this class provides the core methods common among all transport types and
-# mechanisms to start and run the eventmachine reactor which drives all requests.
+# mechanisms to start and run the subsystems which drives all requests.
+#
+# A subclass of RJR::Node should be defined for each transport that is supported.
+# Each subclass should define 
+#  * RJR_NODE_TYPE - unique id of the transport
+#  * listen method - begin listening for new requests and return
+#  * send_message(msg, connection) - send message using the specified connection (transport dependent)
+#  * invoke - establish connection, send message, and wait for / return result
+#  * notify - establish connection, send message, and immediately return
+#
+# Not all methods necessarily have to be implemented depending on the context /
+# use of the node, and the base node class provides many utility methods which
+# to assist in message processing (see below).
 #
-# A subclass of RJR::Node should be defined for each transport that is supported,
-# implementing the 'listen' operation to listen for new requests and 'invoke_request'
-# to issue them.
+# See nodes residing in lib/rjr/nodes/ for specific examples.
 class Node
-  class << self
-    # @!group Config options
-
-    # Default number of threads to instantiate in local worker pool
-    attr_accessor :default_threads
-
-    # Default timeout after which worker threads are killed
-    attr_accessor :default_timeout
 
-    # @!endgroup
-  end
+  ###################################################################
 
   # Unique string identifier of the node
   attr_reader :node_id
@@ -39,115 +41,207 @@ class Node
   # requests and responses received and sent by node
   attr_accessor :message_headers
 
+  # Dispatcher to use to satisfy requests
+  attr_accessor :dispatcher
+
   # RJR::Node initializer
   #
   # @param [Hash] args options to set on request
-  # @option args [String] :node_id unique id of the node *required*!!!
+  # @option args [String] :node_id unique id of the node
   # @option args [Hash<String,String>] :headers optional headers to set on all json-rpc messages
-  # @option args [Integer] :threads number of handler to threads to instantiate in local worker pool
-  # @option args [Integer] :timeout timeout after which worker thread being run is killed
+  # @option args [Dispatcher] :dispatcher dispatcher to assign to the node
   def initialize(args = {})
-     RJR::Node.default_threads ||=  20
-     RJR::Node.default_timeout ||=  10
+     @connection_event_handlers = {:closed => [], :error => []}
+     @response_lock = Mutex.new
+     @response_cv   = ConditionVariable.new
+     @responses     = []
 
-     @node_id     = args[:node_id]
-     @num_threads = args[:threads]  || RJR::Node.default_threads
-     @timeout     = args[:timeout]  || RJR::Node.default_timeout
-     EMAdapter.init
+     @node_id         = args[:node_id]
+     @dispatcher      = args[:dispatcher] || RJR::Dispatcher.new
+     @message_headers = args.has_key?(:headers) ? {}.merge(args[:headers]) : {}
 
-     @message_headers = {}
-     @message_headers.merge!(args[:headers]) if args.has_key?(:headers)
+     @tp = ThreadPool.instance.start
+     @em = EMAdapter.instance.start
   end
 
-  # Initialize the node, should be called from the event loop
-  # before any operation
-  def init_node
-    EM.error_handler { |e|
-      puts "EventMachine raised critical error #{e} #{e.backtrace}"
-      # TODO dispatch to registered event handlers (unify events system)
-    }
+  # Block until the eventmachine reactor and thread pool have both completed running
+  #
+  # @return self
+  def join
+    @tp.join
+    @em.join
+    self
   end
 
-  # Run a job in event machine.
-  # @param [Callable] bl callback to be invoked by eventmachine
-  def em_run(&bl)
-    # Nodes use shared thread pool to handle requests and free
-    # up the eventmachine reactor to continue processing requests
-    # @see ThreadPool2, ThreadPool2Manager
-    ThreadPool2Manager.init @num_threads, :timeout => @timeout
+  # Immediately terminate the node
+  #
+  # *Warning* this does what it says it does. All running threads, and reactor
+  # jobs are immediately killed
+  #
+  # @return self
+  def halt
+    @em.stop_event_loop
+    @tp.stop
+    self
+  end
 
-    # Nodes make use of an EM helper interface to schedule operations
-    EMAdapter.init
+  ##################################################################
 
-    EMAdapter.schedule &bl
+  # Register connection event handler
+  # @param [:error, :close] event the event to register the handler for
+  # @param [Callable] handler block param to be added to array of handlers that are called when event occurs
+  # @yield [Node] self is passed to each registered handler when event occurs
+  def on(event, &handler)
+    if @connection_event_handlers.keys.include?(event)
+      @connection_event_handlers[event] << handler
+    end
   end
 
-  # Run a job async in event machine immediately
-  def em_run_async(&bl)
-    # same init as em_run
-    ThreadPool2Manager.init @num_threads, :timeout => @timeout
-    EMAdapter.init
-    EMAdapter.schedule {
-      ThreadPool2Manager << ThreadPool2Job.new { bl.call }
-    }
+  private
+
+  # Internal helper, run connection event handlers for specified event
+  def connection_event(event)
+    if @connection_event_handlers.keys.include?(event)
+      @connection_event_handlers[event].each { |h|
+        h.call self
+      }
+    end
   end
 
-  # TODO em_schedule
+  ##################################################################
 
-  # Run an job async in event machine.
-  #
-  # This schedules a thread to be run once after a specified
-  # interval via eventmachine
-  #
-  # @param [Integer] seconds interval which to wait before invoking block
-  # @param [Callable] bl callback to be periodically invoked by eventmachine
-  def em_schedule_async(seconds, &bl)
-    # same init as em_run
-    ThreadPool2Manager.init @num_threads, :timeout => @timeout
-    EMAdapter.init
-    EMAdapter.add_timer(seconds) {
-      ThreadPool2Manager << ThreadPool2Job.new { bl.call }
-    }
+  # Internal helper, handle message received
+  def handle_message(msg, connection = {})
+    if RequestMessage.is_request_message?(msg)
+      @tp << ThreadPoolJob.new(msg) { |m| handle_request(m, false, connection) }
+
+    elsif NotificationMessage.is_notification_message?(msg)
+      @tp << ThreadPoolJob.new(msg) { |m| handle_request(m, true, connection) }
+
+    elsif ResponseMessage.is_response_message?(msg)
+      handle_response(msg)
+
+    end
   end
 
-  # Run a job periodically via an event machine timer
-  #
-  # @param [Integer] seconds interval which to invoke block
-  # @param [Callable] bl callback to be periodically invoked by eventmachine
-  def em_repeat(seconds, &bl)
-    # same init as em_run
-    ThreadPool2Manager.init @num_threads, :timeout => @timeout
-    EMAdapter.init
-    EMAdapter.add_periodic_timer seconds, &bl
+  # Internal helper, handle request message received
+  def handle_request(data, notification=false, connection={})
+    # get client for the specified connection
+    # TODO should grap port/ip immediately on connection and use that
+    client_port,client_ip = nil,nil
+    begin
+      # XXX skip if an 'indirect' node type or local
+      unless [:amqp, :local].include?(self.class::RJR_NODE_TYPE)
+        client_port, client_ip =
+          Socket.unpack_sockaddr_in(connection.get_peername)
+      end
+    rescue Exception=>e
+    end
+
+    msg = notification ?
+      NotificationMessage.new(:message => data,
+                              :headers => @message_headers) :
+            RequestMessage.new(:message => data,
+                              :headers => @message_headers)
+
+    result =
+      @dispatcher.dispatch(:rjr_method      => msg.jr_method,
+                           :rjr_method_args => msg.jr_args,
+                           :headers         => msg.headers,
+                           :rjr_client_ip   => client_ip,
+                           :rjr_client_port => client_port,
+                           :rjr_node        => self,
+                           :rjr_node_id     => @node_id,
+                           :rjr_node_type   => self.class::RJR_NODE_TYPE,
+                           :rjr_callback    =>
+                             NodeCallback.new(:node       => self,
+                                              :connection => connection))
+
+    unless notification
+      response = ResponseMessage.new(:id => msg.msg_id,
+                                     :result => result,
+                                     :headers => msg.headers)
+      self.send_msg(response.to_s, connection)
+      return response
+    end
   end
 
-  # Run an job async via an event machine timer.
-  #
-  # This schedules a thread to be run in the thread pool on
-  # every invocation of a periodic event machine timer.
-  #
-  # @param [Integer] seconds interval which to invoke block
-  # @param [Callable] bl callback to be periodically invoked by eventmachine
-  def em_repeat_async(seconds, &bl)
-    # same init as em_schedule
-    ThreadPool2Manager.init @num_threads, :timeout => @timeout
-    EMAdapter.init
-    EMAdapter.add_periodic_timer(seconds){
-      ThreadPool2Manager << ThreadPool2Job.new { bl.call }
+  # Internal helper, handle response message received
+  def handle_response(data)
+    msg    = ResponseMessage.new(:message => data, :headers => self.message_headers)
+    res = err = nil
+    begin
+      res = @dispatcher.handle_response(msg.result)
+    rescue Exception => e
+      err = e
+    end
+
+    @response_lock.synchronize {
+      result = [msg.msg_id, res]
+      result << err if !err.nil?
+      @responses << result
+      @response_cv.broadcast
     }
   end
 
-  # Block until the eventmachine reactor and thread pool have both completed running
-  def join
-    ThreadPool2Manager.join
-    EMAdapter.join
+  # Internal helper, block until response matching message id is received
+  def wait_for_result(message)
+    res = nil
+    while res.nil?
+      @response_lock.synchronize{
+        # FIXME throw err if more than 1 match found
+        res = @responses.find { |response| message.msg_id == response.first }
+        if !res.nil?
+          @responses.delete(res)
+
+        else
+          # FIXME if halt is invoked while this is sleeping, all other threads
+          # may be deleted resulting in this sleeping indefinetly and a deadlock
+
+          # TODO wait for a finite # of seconds, record time we started waiting
+          # before while loop and on every iteration check to see if we've been
+          # waiting longer than an optional timeout. If so throw an error (also
+          # need mechanism to discard result if it comes in later).
+          # finite # of seconds we wait and optional timeout should be
+          # configurable on node class
+          @response_cv.wait @response_lock
+
+        end
+      }
+    end
+    return res
   end
 
-  # Immediately terminate the node
-  def halt
-    EMAdapter.halt
-    ThreadPool2Manager.stop
+end # class Node
+
+# Node callback interface, used to invoke json-rpc methods
+# against a remote node via node connection previously established
+#
+# After a node sends a json-rpc request to another, the either node may send
+# additional requests to each other via the connection already established until
+# it is closed on either end
+class NodeCallback
+
+  # NodeCallback initializer
+  # @param [Hash] args the options to create the node callback with
+  # @option args [node] :node node used to send messages
+  # @option args [connection] :connection connection to be used in channel selection
+  def initialize(args = {})
+    @node        = args[:node]
+    @connection  = args[:connection]
   end
 
+  def notify(callback_method, *data)
+    # XXX return if node type does not support
+    # pesistent conntections (throw err instead?)
+    return if @node.class::RJR_NODE_TYPE == :web
+
+    msg = NotificationMessage.new :method => callback_method,
+                                  :args => data, :headers => @node.message_headers
+
+    # TODO surround w/ begin/rescue block incase of socket errors / raise RJR::ConnectionError
+    @node.send_msg msg.to_s, @connection
+  end
 end
+
 end # module RJR

data/lib/rjr/nodes/amqp.rb

@@ -0,0 +1,216 @@
+# RJR AMQP Node
+#
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the AMQP protocol
+#
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
+# Licensed under the Apache License, Version 2.0
+
+skip_module = false
+begin
+require 'amqp'
+rescue LoadError
+  skip_module = true
+end
+
+if skip_module
+# TODO output: "amqp gem could not be loaded, skipping amqp node definition"
+require 'rjr/nodes/missing'
+RJR::Nodes::AMQP = RJR::Nodes::Missing
+
+else
+require 'thread'
+require 'rjr/node'
+require 'rjr/message'
+
+module RJR
+module Nodes
+
+# AMQP node definition, implements the {RJR::Node} interface to
+# listen for and invoke json-rpc requests over the
+# Advanced Message Queuing Protocol.
+#
+# Clients should specify the amqp broker to connect to when initializing
+# a node and specify the remote queue when invoking requests.
+#
+# @example Listening for json-rpc requests over amqp
+#   # initialize node,
+#   server = RJR::Nodes::AMQP.new :node_id => 'server', :broker => 'localhost'
+#
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   server.dispatcher.handle('hello') do |name|
+#     "Hello #{name}!"
+#   end
+#
+#   # listen, and block
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over amqp
+#   client = RJR::Nodes::AMQP.new :node_id => 'client', :broker => 'localhost'
+#   puts client.invoke('server-queue', 'hello', 'mo') # the queue name is set to "#{node_id}-queue"
+#
+class AMQP < RJR::Node
+  RJR_NODE_TYPE = :amqp
+
+  private
+
+  # Internal helper, initialize the amqp subsystem
+  def init_node(&on_init)
+     if !@conn.nil? && @conn.connected?
+       on_init.call
+       return
+     end
+
+     @conn = ::AMQP.connect(:host => @broker) do |*args|
+       on_init.call
+     end
+     @conn.on_tcp_connection_failure { puts "OTCF #{@node_id}" }
+
+     # TODO move the rest into connect callback ?
+
+     ### connect to qpid broker
+     @channel = ::AMQP::Channel.new(@conn)
+
+     # qpid constructs that will be created for node
+     @queue_name  = "#{@node_id.to_s}-queue"
+     @queue       = @channel.queue(@queue_name, :auto_delete => true)
+     @exchange    = @channel.default_exchange
+
+     @listening = false
+     #@disconnected = false
+
+     @exchange.on_return do |basic_return, metadata, payload|
+         puts "#{payload} was returned! reply_code = #{basic_return.reply_code}, reply_text = #{basic_return.reply_text}"
+         #@disconnected = true # FIXME member will be set on wrong class
+         # TODO these are only run when we fail to send message to queue, need to detect when that queue is shutdown & other events
+         connection_event(:error)
+         connection_event(:closed)
+     end
+  end
+
+  # Internal helper, subscribe to messages using the amqp queue
+  def subscribe
+    if @listening
+      return
+    end
+
+    @amqp_lock.synchronize {
+      @listening = true
+      @queue.subscribe do |metadata, msg|
+        # swap reply to and routing key
+        handle_message(msg, {:routing_key => metadata.reply_to, :reply_to => @queue_name})
+      end
+    }
+    nil
+  end
+
+  public
+
+  # AMQPNode initializer
+  #
+  # @param [Hash] args the options to create the amqp node with
+  # @option args [String] :broker the amqp message broker which to connect to
+  def initialize(args = {})
+     super(args)
+     @broker        = args[:broker]
+     @amqp_lock     = Mutex.new
+  end
+
+  # Publish a message using the amqp exchange
+  #
+  # Implementation of {RJR::Node#send_msg}
+  def send_msg(msg, metadata, &on_publish)
+    @amqp_lock.synchronize {
+      #raise RJR::Errors::ConnectionError.new("client unreachable") if @disconnected
+      routing_key = metadata[:routing_key]
+      reply_to    = metadata[:reply_to]
+      @exchange.publish msg,
+                        :routing_key => routing_key,
+                        :reply_to => reply_to do |*cargs|
+        on_publish.call unless on_publish.nil?
+      end
+    }
+    nil
+  end
+
+  # Instruct Node to start listening for and dispatching rpc requests.
+  #
+  # Implementation of {RJR::Node#listen}
+  def listen
+    @em.schedule do
+      init_node {
+        subscribe # start receiving messages
+      }
+    end
+    self
+  end
+
+  # Instructs node to send rpc request, and wait for and return response.
+  #
+  # Implementation of {RJR::Node#invoke}
+  #
+  # Do not invoke directly from em event loop or callback as will block the message
+  # subscription used to receive responses
+  #
+  # @param [String] routing_key destination queue to send request to
+  # @param [String] rpc_method json-rpc method to invoke on destination
+  # @param [Array] args array of arguments to convert to json and invoke remote method wtih
+  # @return [Object] the json result retrieved from destination converted to a ruby object
+  # @raise [Exception] if the destination raises an exception, it will be converted to json and re-raised here 
+  def invoke(routing_key, rpc_method, *args)
+    message = RequestMessage.new :method => rpc_method,
+                                 :args   => args,
+                                 :headers => @message_headers
+    @em.schedule do
+      init_node {
+        subscribe # begin listening for result
+        send_msg(message.to_s, :routing_key => routing_key, :reply_to => @queue_name)
+      }
+    end
+
+    # TODO optional timeout for response
+    result = wait_for_result(message)
+
+    if result.size > 2
+      raise Exception, result[2]
+    end
+    return result[1]
+  end
+
+  # FIXME add method to instruct node to send rpc request, and immediately
+  #        return / ignoring response & also add method to collect response
+  #        at a later time
+
+  # Instructs node to send rpc notification (immadiately returns / no response is generated)
+  #
+  # Implementation of {RJR::Node#notify}
+  #
+  # @param [String] routing_key destination queue to send request to
+  # @param [String] rpc_method json-rpc method to invoke on destination
+  # @param [Array] args array of arguments to convert to json and invoke remote method wtih
+  def notify(routing_key, rpc_method, *args)
+    # will block until message is published
+    published_l = Mutex.new
+    published_c = ConditionVariable.new
+
+    invoked = false
+    message = NotificationMessage.new :method => rpc_method,
+                                      :args   => args,
+                                      :headers => @message_headers
+    @em.schedule do
+      init_node {
+        send_msg(message.to_s, :routing_key => routing_key, :reply_to => @queue_name){
+          published_l.synchronize { invoked = true ; published_c.signal }
+        }
+      }
+    end
+    published_l.synchronize { published_c.wait published_l unless invoked }
+    nil
+  end
+
+end # class AMQP
+
+end # module Nodes
+end # module RJR 
+
+end # (!skip_module)