rjr 0.7.0 → 0.8.0

data/lib/rjr/dispatcher.rb

@@ -1,25 +1,50 @@
 # RJR Request / Response Dispatcher
 #
+# Representation of a json-rpc request, response and mechanisms which to
+# register methods to handle requests and return responses
+#
 # 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 'rjr/common'
 
 module RJR
 
+# JSON-RPC request representation
 class Request
+  # name of the method which request is for
   attr_accessor :method
+
+  # array of arguments which to pass to the rpc method handler
   attr_accessor :method_args
+
+  # hash of keys/values corresponding to optional headers received as part of of the request
   attr_accessor :headers
+
+  # callback through which additional requests may be invoked
   attr_accessor :rjr_callback
+
+  # type of the rjr node which request was received on
   attr_accessor :rjr_node_type
+
+  # id of the rjr node which request was received on
   attr_accessor :rjr_node_id
 
+  # callable object registered to the specified method which to invoke request on with arguments
   attr_accessor :handler
 
+  # RJR request intializer
+  # @param [Hash] args options to set on request
+  # @option args [String] :method name of the method which request is for
+  # @option args [Array]  :method_args array of arguments which to pass to the rpc method handler
+  # @option args [Hash]   :headers hash of keys/values corresponding to optional headers received as part of of the request
+  # @option args [String] :client_ip ip address of client which invoked the request (if applicable)
+  # @option args [String] :client_port port of client which invoked the request (if applicable)
+  # @option args [RJR::Callback] :rjr_callback callback through which additional requests may be invoked
+  # @option args [RJR::Node] :rjr_node rjr node which request was received on
+  # @option args [String] :rjr_node_id id of the rjr node which request was received on
+  # @option args [Symbol] :rjr_node_type type of the rjr node which request was received on
+  # @option args [Callable] :handler callable object registered to the specified method which to invoke request on with arguments
   def initialize(args = {})
     @method       = args[:method]
     @method_args  = args[:method_args]
@@ -33,6 +58,8 @@ class Request
     @handler       = args[:handler]
   end
 
+  # Actually invoke the request by calling the registered handler with the specified
+  # method parameters in the local scope
   def handle
     RJR::Logger.info "Dispatching '#{@method}' request with parameters (#{@method_args.join(',')}) on #{@rjr_node_type}-node(#{@rjr_node_id})"
     retval = instance_exec(*@method_args, &@handler)
@@ -41,14 +68,32 @@ class Request
   end
 end
 
+# JSON-RPC result representation
 class Result
+  # boolean indicating if request was successfully invoked
   attr_accessor :success
+
+  # boolean indicating if request was not successfully invoked
   attr_accessor :failed
+
+  # return value of the json-rpc call if successful
   attr_accessor :result
+
+  # code corresponding to json-rpc error if problem occured during request invocation
   attr_accessor :error_code
+
+  # message corresponding to json-rpc error if problem occured during request invocation
   attr_accessor :error_msg
+
+  # class of error raised (if any) during request invocation (this is extra metadata beyond standard json-rpc)
   attr_accessor :error_class
 
+  # RJR result intializer
+  # @param [Hash] args options to set on result
+  # @option args [Object] :result result of json-rpc method handler if successfully returned
+  # @option args [Integer] :error_code code corresponding to json-rpc error if problem occured during request invocation
+  # @option args [String] :error_msg message corresponding to json-rpc error if problem occured during request invocation
+  # @option args [Class] :error_class class of error raised (if any) during request invocation (this is extra metadata beyond standard json-rpc)
   def initialize(args = {})
     @result        = nil
     @error_code    = nil
@@ -70,6 +115,8 @@ class Result
     end
   end
 
+  # Compare Result against other result, returning true if both correspond
+  # to equivalent json-rpc results else false
   def ==(other)
     @success == other.success &&
     @failed  == other.failed  &&
@@ -79,17 +126,20 @@ class Result
     @error_class == other.error_class
   end
 
+  # Convert Response to human consumable string
   def to_s
     "#{@success} #{@result} #{@error_code} #{@error_msg} #{@error_class}"
   end
 
   ######### Specific request types
 
+  # JSON-RPC -32600 / Invalid Request
   def self.invalid_request
      return Result.new(:error_code => -32600,
                        :error_msg => '  Invalid Request')
   end
 
+  # JSON-RPC -32602 / Method not found
   def self.method_not_found(name)
      return Result.new(:error_code => -32602,
                        :error_msg => "Method '#{name}' not found")
@@ -97,15 +147,33 @@ class Result
 
 end
 
+# Association between json-rpc method name and registered handler to
+# be invoked on new requests.
+#
+# When invoked, creates new {RJR::Request} object with specified request
+# params and uses it to invoke handler in its context. Formats and returns
+# return of operation
 class Handler
   attr_accessor :method_name
   attr_accessor :handler_proc
 
+  # RJR::Handler intializer
+  # @param [Hash] args options to set on handler
+  # @option args [String] :method name of json-rpc method to which handler is bound
+  # @option args [Callable] :handle callable object which to bind to method name
   def initialize(args = {})
     @method_name          = args[:method]
     @handler_proc         = args[:handler]
   end
 
+  # Handle new json-rpc request to registered method.
+  #
+  # Creates new {RJR::Request} with the local method name and handler and the
+  # arguments received as part of the request. Uses it to invoke handler and
+  # creates and returns new {RJR::Result} encapsulating the return value if
+  # successful or error code/message/class if not.
+  #
+  # If invalid method_name is specified returns a json-rpc 'Method not found'
   def handle(args = {})
     return Result.method_not_found(args[:missing_name]) if @method_name.nil?
 
@@ -126,13 +194,39 @@ class Handler
   end
 end
 
+# Primary RJR JSON-RPC method dispatcher interface.
+#
+# Provides class methods which to register global handlers to json-rpc methods and
+# to handle requests and responses.
 class Dispatcher
-  # clear handlers
+  # Clear all registered json-rpc handlers
   def self.init_handlers
     @@handlers = {}
   end
 
-  # register a handler to the specified method
+  # Register a handler for the specified method(s)
+  #
+  # *WARNING* Do not invoke 'return' in registered handlers as these are blocks and *not* lambdas
+  # (see {http://stackoverflow.com/questions/626/when-to-use-lambda-when-to-use-proc-new Ruby Lambdas vs Procs})
+  #
+  # If specifying a single method name pass in a string, else pass in an array of strings.
+  # The block argument will be used as the method handler and will be invoked when
+  # json-rpc requests are received corresponding to the method name(s)
+  # @param [String,Array<String>] method_names one or more string method names
+  # @param [Hash] args options to initialize handler with, current unused
+  # @param [Callable] handler block to invoke when json-rpc requests to method are received
+  #
+  # @example
+  #   RJR::Dispatcher.add_handler("hello_world") {
+  #     "hello world"
+  #   }
+  #
+  #   RJR::Dispatcher.add_handler(["echo", "ECHO"]) { |val|
+  #     val
+  #   }
+  #
+  # # TODO define yard macros to construct documentation for a rjr based api
+  #        from calls to add_handler
   def self.add_handler(method_names, args = {}, &handler)
     method_names = Array(method_names) unless method_names.is_a?(Array)
     @@handlers  ||= {}
@@ -142,7 +236,8 @@ class Dispatcher
     }
   end
 
-  # Helper to handle request messages
+  # Helper used by RJR nodes to dispatch requests received via transports to
+  # registered handlers.
   def self.dispatch_request(method_name, args = {})
      @@handlers  ||= {}
      handler  = @@handlers[method_name]
@@ -155,7 +250,8 @@ class Dispatcher
      return handler.handle args
   end
 
-  # Helper to handle response messages
+  # Helper used by RJR nodes to handle responses received from rjr requests
+  #   (returns return-value of method handler or raises error)
   def self.handle_response(result)
      unless result.success
        #if result.error_class

data/lib/rjr/errors.rb

@@ -3,12 +3,14 @@
 # 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
-
 module RJR
+
+# The RJR::Errors module provides a mechanism to dynamically create errors
+# on demand as they are needed. At some point this will go away / be replaced
+# with a more rigidly / fixed defined error heirarchy.
 module Errors
 
+# Catches all Errors constants and define new RuntimeError subclass
 def self.const_missing(error_name)  # :nodoc:
   if error_name.to_s =~ /Error\z/
     const_set(error_name, Class.new(RuntimeError))

data/lib/rjr/local_node.rb

@@ -1,23 +1,25 @@
 # RJR Local Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests via local method calls
+#
 # 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 'rjr/node'
 require 'rjr/message'
 
 module RJR
 
-# Local client node callback interface,
-# send data back to client via local handlers
+# Local node callback interface, used to invoke local json-rpc method handlers
 class LocalNodeCallback
+  # LocalNodeCallback initializer
+  # @param [Hash] args the options to create the local node callback with
+  # @option args [LocalNode] :node local node used to send/receive messages
   def initialize(args = {})
     @node        = args[:node]
   end
 
+  # Implementation of {RJR::NodeCallback#invoke}
   def invoke(callback_method, *data)
     # TODO any exceptions from handler will propagate here, surround w/ begin/rescue block
     @node.invoke_request(callback_method, *data)
@@ -25,34 +27,58 @@ class LocalNodeCallback
   end
 end
 
-# Local node definition, listen for and invoke json-rpc
-# requests via local handlers
+# Local node definition, implements the {RJR::Node} interface to
+# listen for and invoke json-rpc requests via local handlers
+#
+# This is useful for situations in which you would like to invoke registered
+# json-rpc handlers locally, enforcing the same constraints as
+# you would on a json-rpc request coming in remotely.
+#
+# @example Listening for and dispatching json-rpc requests locally
+#   RJR::Dispatcher.add_handler('hello') { |name|
+#     @rjr_node_type == :local ? "Hello superuser #{name}" : "Hello #{name}!"
+#   }
+#
+#   # initialize node and invoke request
+#   node = RJR::LocalNode.new :node_id => 'node'
+#   node.invoke_request('hello', 'mo')
+#
 class LocalNode < RJR::Node
   RJR_NODE_TYPE = :local
 
-  # allow clients to override the node type for the local node
+  # allows clients to override the node type for the local node
   attr_accessor :node_type
 
-  # initialize the node w/ the specified params
+  # LocalNode initializer
+  # @param [Hash] args the options to create the local node with
   def initialize(args = {})
      super(args)
      @node_type = RJR_NODE_TYPE
   end
 
   # register connection event handler,
-  # until we support manual disconnections of the local node, we don't
-  # have to do anything here
+  # *note* Until we support manual disconnections of the local node, we don't have to do anything here
+  #
+  # @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 [LocalNode] self is passed to each registered handler when event occurs
   def on(event, &handler)
     # TODO raise error (for the time being)?
   end
 
   # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Currently does nothing as method handlers can be invoked directly upon invoke_request
   def listen
     em_run do
     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] 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(rpc_method, *args)
     0.upto(args.size).each { |i| args[i] = args[i].to_s if args[i].is_a?(Symbol) }
     message = RequestMessage.new :method => rpc_method,

data/lib/rjr/message.rb

@@ -1,5 +1,7 @@
 # RJR Message
 #
+# Representations of json-rpc messages in accordance with the standard
+#
 # Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
@@ -18,12 +20,34 @@ class RequestMessage
         Array.new(16) {|x| rand(0xff) }
   end
 
+  # Message string received from the source
   attr_accessor :json_message
+
+  # Method source is invoking on the destination
   attr_accessor :jr_method
+
+  # Arguments source is passing to destination method
   attr_accessor :jr_args
+
+  # ID of the message in accordance w/ json-rpc specification
   attr_accessor :msg_id
+
+  # Optional headers to add to json outside of standard json-rpc request
   attr_accessor :headers
 
+  # RJR Request Message initializer
+  #
+  # This should be invoked with one of two argument sets. If creating a new message
+  # to send to the server, specify :method, :args, and :headers to include in the message
+  # (message id will be autogenerated). If handling an new request message sent from the
+  # client, simply specify :message and optionally any additional headers (they will 
+  # be merged with the headers contained in the message)
+  #
+  # @param [Hash] args options to set on request
+  # @option args [String] :message json string received from sender
+  # @option args [Hash] :headers optional headers to set in request and subsequent messages
+  # @option args [String] :method method to invoke on server
+  # @option args [Array<Object>] :args to pass to server method, all must be convertable to/from json
   def initialize(args = {})
     if args.has_key?(:message)
       begin
@@ -52,6 +76,10 @@ class RequestMessage
     end
   end
 
+  # Class helper to determine if the specified string is a valid json-rpc
+  # method request
+  # @param [String] message string message to check
+  # @return [true,false] indicating if message is request message
   def self.is_request_message?(message)
     begin
        # TODO log error
@@ -61,6 +89,7 @@ class RequestMessage
     end
   end
 
+  # Convert request message to string json format
   def to_s
     request = { 'jsonrpc' => '2.0',
                 'method' => @jr_method,
@@ -72,13 +101,34 @@ class RequestMessage
 
 end
 
-# Message sent from server to client in response to request message
+# Message sent from server to client in response to json-rpc request message
 class ResponseMessage
+  # Message string received from the source
   attr_accessor :json_message
+
+  # ID of the message in accordance w/ json-rpc specification
   attr_accessor :msg_id
+
+  # Result encapsulated in the response message
+  # @see RJR::Result
   attr_accessor :result
+
+  # Optional headers to add to json outside of standard json-rpc request
   attr_accessor :headers
 
+  # ResponseMessage initializer
+  #
+  # This should be invoked with one of two argument sets. If creating a new message
+  # to send to the client, specify :id, :result, and :headers to include in the message.
+  # If handling an new request message sent from the client, simply specify :message
+  # and optionally any additional headers (they will be merged with the headers contained
+  # in the message)
+  #
+  # @param [Hash] args options to set on request
+  # @option args [String] :message json string received from sender
+  # @option args [Hash] :headers optional headers to set in request and subsequent messages
+  # @option args [String] :id id to set in response message, should be same as that in received message
+  # @option args [RJR::Result] :result result of json-rpc method invocation
   def initialize(args = {})
     if args.has_key?(:message)
       response = JSON.parse(args[:message])
@@ -115,6 +165,10 @@ class ResponseMessage
 
   end
 
+  # Class helper to determine if the specified string is a valid json-rpc
+  # method response
+  # @param [String] message string message to check
+  # @return [true,false] indicating if message is response message
   def self.is_response_message?(message)
     begin
       json = JSON.parse(message)
@@ -125,6 +179,7 @@ class ResponseMessage
     end
   end
 
+  # Convert request message to string json format
   def to_s
     s = ''
     if result.success

data/lib/rjr/multi_node.rb

@@ -1,30 +1,57 @@
 # RJR MultiNode Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests over multiple protocols
+#
 # 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 'eventmachine'
 require 'rjr/node'
 require 'rjr/message'
 
 module RJR
 
+# Multiple node definition, allows a developer to easily multiplex transport
+# mechanisms to serve JSON-RPC requests over.
+#
+# @example Listening for json-rpc requests over amqp, tcp, http, and websockets
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   RJR::Dispatcher.add_handler('hello') { |name|
+#     # optionally use @rjr_node_type to handle different transport types
+#     "Hello #{name}!"
+#   }
+#
+#   amqp_server = RJR::TCPNode.new :node_id => 'amqp_server', :broker => 'localhost'
+#   tcp_server  = RJR::TCPNode.new :node_id => 'tcp_server',  :host => 'localhost', :port => '7777'
+#   web_server  = RJR::WebNode.new :node_id => 'tcp_server',  :host => 'localhost', :port => '80'
+#   ws_server   = RJR::WebNode.new :node_id => 'tcp_server',  :host => 'localhost', :port => '8080'
+#
+#   server = RJR::MultiNode.new :node_id => 'server',
+#                               :nodes   => [amqp_server, tcp_server, web_server, ws_server]
+#   server.listen
+#   server.join
+#
+#   # invoke requests as you normally would via any protocol
+#
 class MultiNode < RJR::Node
-  # initialize the node w/ the specified params
+  # MultiNode initializer
+  # @param [Hash] args the options to create the tcp node with
+  # @option args [Array<RJR::Node>] :nodes array of nodes to use to listen to new requests on
   def initialize(args = {})
     super(args)
     @nodes = args[:nodes]
   end
 
+  # Add node to multinode
+  # @param [RJR::Node] node the node to add
   def <<(node)
     @nodes << node
   end
 
 
   # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
   def listen
     @nodes.each { |node|
       node.listen