rjr 0.7.0 → 0.8.0

data/README.md

@@ -0,0 +1,144 @@
+## RJR - Ruby Json Rpc Library ##
+
+Copyright (C) 2012 Mo Morsi <mo@morsi.org>
+
+RJR is made available under the Apache License, Version 2.0
+
+RJR is an implementation of the {http://en.wikipedia.org/wiki/JSON-RPC JSON-RPC}
+Version 2.0 Specification. It allows a developer to register custom JSON-RPC
+method handlers which may be invoked simultaneously over a variety of transport
+mechanisms.
+
+Currently supported transports include:
+    tcp, amqp, http (post), websockets, local method calls, (udp coming soon)
+
+### Intro ###
+To install rjr simply run:
+    gem install rjr
+
+Source code is available via:
+    git clone http://github.com/movitto/rjr
+
+### Using ###
+
+Simply require rubygems and the rjr library
+
+    require 'rubygems'
+    require 'rjr'
+
+server.rb:
+
+    # define a rpc method called 'hello' which takes
+    # one argument and returns it in upper case
+    RJR::Dispatcher.add_handler("hello") { |arg|
+      arg.upcase
+    }
+
+    # listen for this method via amqp, websockets, http, and via local calls
+    amqp_node  = RJR::AMQPNode.new  :node_id => 'server', :broker => 'localhost'
+    ws_node    = RJR::WSNode.new    :node_id => 'server', :host   => 'localhost', :port => 8080
+    www_node   = RJR::WebNode.new   :node_id => 'server', :host   => 'localhost', :port => 8888
+    local_node = RJR::LocalNode.new :node_id => 'server'
+
+    # start the server and block
+    multi_node = RJR::MultiNode.new :nodes => [amqp_node, ws_node, www_node, local_node]
+    multi_node.listen
+    multi_node.join
+
+
+amqp_client.rb:
+
+    # invoke the method over amqp
+    amqp_node = RJR::AMQPNode.new :node_id => 'client', :broker => 'localhost'
+    puts amqp_node.invoke_request('server-queue', 'hello', 'world')
+
+
+ws_client.js:
+
+    // use the js client to invoke the method via a websocket
+    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
+    <script type="text/javascript" src="site/json.js" />
+    <script type="text/javascript" src="site/jrw.js" />
+    <script type="text/javascript">
+    var node = new WSNode('127.0.0.1', '8080');
+    node.onopen = function(){
+      node.invoke_request('hello', 'rjr');
+    };
+    node.onsuccess = function(result){
+      alert(result);
+    };
+    node.open();
+    </script>
+
+### Reference ###
+
+The source repository can be found {https://github.com/movitto/rjr here}
+
+Online API documentation and examples can be found {http://rubydoc.info/github/movitto/rjr here}
+
+Generate documentation via
+
+    rake yard
+
+Also see specs for detailed usage.
+
+### Advanced ###
+
+RJR uses {http://rubyeventmachine.com/ eventmachine} to process server requests.
+Upon being received requests are handed off to a thread pool to free up the reactor.
+It is up to the developer to ensure resources accessed in the method handlers
+are protected from concurrent access.
+
+Various metadata fields are made available to json-rpc method handlers through
+instance variables. These include:
+
+
+<pre>* @rjr_node
+* @rjr_node_id
+* @rjr_node_type
+* @rjr_callback
+* @headers
+* @client_ip
+* @client_port
+* @method
+* @method_args
+* @handler
+</pre>
+
+RJR implements a callback interface through which methods may be invoked on a client
+after an initial server connection is established. Store and/or invoke @rjr_callback to make
+use of this.
+
+    RJR::Dispatcher.add_handler("register_callback") { |*args|
+      $my_registry.invoke_me_later {
+        # rjr callback will already be setup to send messages to the correct client
+        @rjr_callback.invoke 'callback_method', 'with', 'custom', 'params'
+      }
+    }
+
+RJR also permits arbitrary headers being set on JSON-RPC requests and responses. These
+will be stored in the json send to/from nodes, at the same level/scope as the message
+'id', 'method', and 'params' properties. Developers using RJR may set and leverage these headers
+in their registered handlers to store additional metadata to extend the JSON-RPC protocol and
+support any custom subsystems (an auth subsystem for example)
+
+    RJR::Dispatcher.add_handler("login") { |*args|
+      if $my_user_registry.find(:user => args.first, :pass => args.last)
+        @headers['session-id'] = $my_user_registry.create_session.id
+      end
+    }
+
+    RJR::Dispatcher.add_handler("do_secure_action") { |*args|
+      if $my_user_registry.find(:session_id => @headers['session-id']).nil?
+        raise PermissionError, "invalid session"
+      end
+      # ...
+    }
+
+Of course any custom headers set/used will only be of use to JSON-RPC nodes running
+RJR as this is not standard JSON-RPC.
+
+
+### Authors ###
+Mo Morsi <mo@morsi.org>
+Ladislav Smola <ladislav.smola@it-logica.cz>

data/Rakefile

@@ -3,7 +3,7 @@
 # Copyright (C) 2010-2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
-require 'rdoc/task'
+require "yard"
 require "rspec/core/rake_task"
 
 desc "Run all specs"
@@ -26,12 +26,12 @@ task :integration do
   system("tests/integration/runner")
 end
 
-Rake::RDocTask.new do |rd|
-    rd.main = "README.rdoc"
-    rd.rdoc_dir = "doc/site/api"
-    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+YARD::Rake::YardocTask.new do |t|
+  #t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+  #t.options = ['--any', '--extra', '--opts'] # optional
 end
 
+
 desc "build the rjr gem"
 task :build do
   system "gem build rjr.gemspec"

data/bin/rjr-server

@@ -45,7 +45,8 @@ def main()
   rjr_node = RJR::MultiNode.new :nodes => [amqp_node, ws_node, www_node]
 
   rjr_node.listen
-  rjr_node.terminate # TODO run in signal handler
+  rjr_node.join
+  rjr_node.stop # TODO run in signal handler
 end
 
 main()

data/lib/rjr.rb

@@ -3,6 +3,9 @@
 # Copyright (C) 2010-2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
+# rjr - Ruby Json Rpc
+module RJR ; end
+
 require 'rjr/common'
 require 'rjr/errors'
 require 'rjr/thread_pool'

data/lib/rjr/amqp_node.rb

@@ -1,11 +1,10 @@
 # RJR AMQP Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the AMQP protocol
+#
 # Copyright (C) 2012 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 'amqp'
 require 'thread'
 require 'rjr/node'
@@ -13,25 +12,57 @@ require 'rjr/message'
 
 module RJR
 
-# AMQP client node callback interface,
-# send data back to client via AMQP.
+# AMQP node callback interface, used to invoke json-rpc methods on a
+# remote node which previously invoked a method on the local one.
+#
+# After a node sends a json-rpc request to another, the either node may send
+# additional requests to each other via amqp through this callback interface
+# until the queues are closed
 class AMQPNodeCallback
+
+  # AMQPNodeCallback initializer
+  # @param [Hash] args the options to create the amqp node callback with
+  # @option args [AMQPNode] :node amqp node used to send/receive messages
+  # @option args [String]   :destination name of the queue to invoke callbacks on
   def initialize(args = {})
     @node        = args[:node]
     @destination = args[:destination]
   end
 
+  # Implementation of {RJR::NodeCallback#invoke}
   def invoke(callback_method, *data)
     msg = RequestMessage.new :method => callback_method, :args => data, :headers => @message_headers
     @node.publish msg.to_s, :routing_key => @destination, :mandatory => true
   end
 end
 
-# AMQP node definition, listen for and invoke json-rpc requests  over AMQP
-class AMQPNode < RJR::Node
+# AMQP node definition, implements the {RJR::Node} interface to
+# listen for and invoke json-rpc requests over
+# {http://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol AMQP}.
+#
+# 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
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   RJR::Dispatcher.add_handler('hello') { |name|
+#     "Hello #{name}!"
+#   }
+#
+#   # initialize node, listen, and block
+#   server = RJR::AMQPNode.new :node_id => 'server', :broker => 'localhost'
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over amqp
+#   client = RJR::AMQPNode.new :node_id => 'client', :broker => 'localhost'
+#   puts client.invoke_request('server-queue', 'hello', 'mo') # the queue name is set to "#{node_id}-queue"
+class  AMQPNode < RJR::Node
   RJR_NODE_TYPE = :amqp
 
   private
+
+  # Internal helper, handle message pulled off queue
   def handle_message(metadata, msg)
     if RequestMessage.is_request_message?(msg)
       reply_to = metadata.reply_to
@@ -43,6 +74,7 @@ class AMQPNode < RJR::Node
     end
   end
 
+  # Internal helper, handle request message pulled off queue
   def handle_request(reply_to, message)
     msg    = RequestMessage.new(:message => message, :headers => @message_headers)
     headers = @message_headers.merge(msg.headers) # append request message headers
@@ -63,6 +95,7 @@ class AMQPNode < RJR::Node
     publish response.to_s, :routing_key => reply_to
   end
 
+  # Internal helper, handle response message pulled off queue
   def handle_response(message)
     msg    = ResponseMessage.new(:message => message, :headers => @message_headers)
     res = err = nil
@@ -80,20 +113,6 @@ class AMQPNode < RJR::Node
     }
   end
 
-  public
-
-  # initialize the node w/ the specified params
-  def initialize(args = {})
-     super(args)
-     @broker    = args[:broker]
-     @connection_event_handlers = {:closed => [], :error => []}
-     @response_lock = Mutex.new
-     @response_cv   = ConditionVariable.new
-     @response_check_cv   = ConditionVariable.new
-     @responses     = []
-     @amqp_lock     = Mutex.new
-  end
-
   # Initialize the amqp subsystem
   def init_node
      return unless @conn.nil? || !@conn.connected?
@@ -119,27 +138,7 @@ class AMQPNode < RJR::Node
      end
   end
 
-  # publish a message using the amqp exchange
-  def publish(*args)
-    @amqp_lock.synchronize {
-      #raise RJR::Errors::ConnectionError.new("client unreachable") if @disconnected
-      @exchange.publish *args
-    }
-    nil
-  end
-
-  # subscribe to messages using the amqp queue
-  def subscribe(*args, &bl)
-    return if @listening
-    @amqp_lock.synchronize {
-      @listening = true
-      @queue.subscribe do |metadata, msg|
-        bl.call metadata, msg
-      end
-    }
-    nil
-  end
-
+  # Internal helper, block until response matching message id is received
   def wait_for_result(message)
     res = nil
     while res.nil?
@@ -150,6 +149,8 @@ class AMQPNode < RJR::Node
         unless res.nil?
           @responses.delete(res)
         else
+          # we can't just go back to waiting for message here, need to give
+          # other nodes a chance to check it first
           @response_cv.signal
           @response_check_cv.wait @response_lock
         end
@@ -159,14 +160,7 @@ class AMQPNode < RJR::Node
     return res
   end
 
-  # register connection event handler
-  def on(event, &handler)
-    if @connection_event_handlers.keys.include?(event)
-      @connection_event_handlers[event] << handler
-    end
-  end
-
-  # run connection event handlers for specified event
+  # Internal helper, run connection event handlers for specified event
   # TODO these are only run when we fail to send message to queue, need to detect when that queue is shutdown & other events
   def connection_event(event)
     if @connection_event_handlers.keys.include?(event)
@@ -176,7 +170,59 @@ class AMQPNode < RJR::Node
     end
   end
 
-  # Instruct Node to start listening for and dispatching rpc requests
+  # Internal helper, subscribe to messages using the amqp queue
+  def subscribe(*args, &bl)
+    return if @listening
+    @amqp_lock.synchronize {
+      @listening = true
+      @queue.subscribe do |metadata, msg|
+        bl.call metadata, msg
+      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]
+     @connection_event_handlers = {:closed => [], :error => []}
+     @response_lock = Mutex.new
+     @response_cv   = ConditionVariable.new
+     @response_check_cv   = ConditionVariable.new
+     @responses     = []
+     @amqp_lock     = Mutex.new
+  end
+
+  # Publish a message using the amqp exchange (*do* *not* *use*).
+  #
+  # XXX hack should be private, declared publically so as to be able to be used by {RJR::AMQPNodeCallback}
+  def publish(*args)
+    @amqp_lock.synchronize {
+      #raise RJR::Errors::ConnectionError.new("client unreachable") if @disconnected
+      @exchange.publish *args
+    }
+    nil
+  end
+
+  # 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 [AMQPNode] 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
+
+  # Instruct Node to start listening for and dispatching rpc requests.
+  #
+  # Implementation of {RJR::Node#listen}
   def listen
     em_run do
       init_node
@@ -188,7 +234,12 @@ class AMQPNode < RJR::Node
     end
   end
 
-  # Instructs node to send rpc request, and wait for / return response
+  # Instructs node to send rpc request, and wait for and return response
+  # @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_request(routing_key, rpc_method, *args)
     message = RequestMessage.new :method => rpc_method,
                                  :args   => args,

data/lib/rjr/common.rb

@@ -1,13 +1,22 @@
 # RJR Utility Methods
 #
-# Copyright (C) 2011 Mohammed Morsi <mo@morsi.org>
+# Assortment of helper methods and methods that don't fit elsewhere
+#
+# Copyright (C) 2011-2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
 require 'logger'
 
 module RJR
 
-# Logger helper class
+# Logger helper class.
+#
+# Encapsulates the standard ruby logger in a thread safe manner. Dispatches
+# class methods to an internally tracked logger to provide global access.
+#
+# @example
+#   RJR::Logger.info 'my message'
+#   RJR::Logger.warn 'my warning'
 class Logger
   private
     def self._instantiate_logger
@@ -39,6 +48,8 @@ class Logger
        @@logger
     end
 
+    # Set log level.
+    # @param level one of the standard rails log levels (default fatal)
     def self.log_level=(level)
       _instantiate_logger
       @@logger.level = level
@@ -48,10 +59,15 @@ end
 end # module RJR
 
 if RUBY_VERSION < "1.9"
-# http://blog.jayfields.com/2006/09/ruby-instanceexec-aka-instanceeval.html
+# We extend object in ruby 1.9 to define 'instance_exec'
+#
+# {http://blog.jayfields.com/2006/09/ruby-instanceexec-aka-instanceeval.html Further reference}
 class Object
   module InstanceExecHelper; end
   include InstanceExecHelper
+  # Execute the specified block in the scope of the local object
+  # @param [Array] args array of args to be passed to block
+  # @param [Callable] block callable object to bind and invoke in the local namespace
   def instance_exec(*args, &block)
     begin
       old_critical, Thread.critical = Thread.critical, true