rjr 0.7.0 → 0.8.0

data/lib/rjr/node.rb

@@ -11,19 +11,51 @@ require 'rjr/thread_pool'
 
 module RJR
 
-# Defines a node which can be used to dispatch rpc requests and/or register
-# handlers for incomping requests.
+# 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.
+#
+# 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.
 class Node
-  # node always has a node id
+  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
 
-  # attitional parameters to set on messages
+  # Attitional header fields to set on all
+  # requests and responses received and sent by node
   attr_accessor :message_headers
 
+  # Nodes use internal thread pools to handle requests and free
+  # up the eventmachine reactor to continue processing requests
+  # @see ThreadPool
   attr_reader :thread_pool
 
+  # RJR::Node initializer
+  # @param [Hash] args options to set on request
+  # @option args [String] :node_id unique id of the node *required*!!!
+  # @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
   def initialize(args = {})
-     @node_id = args[:node_id]
+     RJR::Node.default_threads ||=  15
+     RJR::Node.default_timeout ||=  5
+
+     @node_id     = args[:node_id]
+     @num_threads = args[:threads]  || RJR::Node.default_threads
+     @timeout     = args[:timeout]  || RJR::Node.default_timeout
 
      @message_headers = {}
      @message_headers.merge!(args[:headers]) if args.has_key?(:headers)
@@ -31,11 +63,23 @@ class Node
      ObjectSpace.define_finalizer(self, self.class.finalize(self))
   end
 
+  # Ruby ObjectSpace finalizer to ensure that node terminates all
+  # operations when object is destroyed
   def self.finalize(node)
     proc { node.halt ; node.join }
   end
 
-  # run job in event machine
+  # Run a job in event machine.
+  #
+  # This will start the eventmachine reactor and thread pool if not already
+  # running, schedule the specified block to be run and immediately return.
+  #
+  # For use by subclasses to start listening and sending operations within
+  # the context of event machine.
+  #
+  # Keeps track of an internal counter of how many times this was invoked so
+  # a specific node can be shutdown / started up without affecting the
+  # eventmachine reactor (@see #stop)
   def em_run(&bl)
     @@em_jobs ||= 0
     @@em_jobs += 1
@@ -44,8 +88,7 @@ class Node
 
     unless !@thread_pool.nil? && @thread_pool.running?
       # threads pool to handle incoming requests
-      # FIXME make the # of threads and timeout configurable)
-      @thread_pool = ThreadPool.new(10, :timeout => 5)
+      @thread_pool = ThreadPool.new(@num_threads, :timeout => @timeout)
     end
 
     if @@em_thread.nil?
@@ -63,10 +106,12 @@ class Node
     EventMachine.schedule bl
   end
 
+  # Returns boolean indicating if this node is still running or not
   def em_running?
     @@em_jobs > 0 && EventMachine.reactor_running?
   end
 
+  # Block until the eventmachine reactor and thread pool have both completed running
   def join
     @@em_thread.join if @@em_thread
     @@em_thread = nil
@@ -74,6 +119,8 @@ class Node
     @thread_pool = nil
   end
 
+  # Decrement the event machine job counter and if equal to zero,
+  # immediately terminate the node
   def stop
     @@em_jobs -= 1
     if @@em_jobs == 0
@@ -82,6 +129,8 @@ class Node
     end
   end
 
+  # Immediately terminate the node, halting the eventmachine reactor and
+  # terminating the thread pool
   def halt
     @@em_jobs = 0
     EventMachine.stop

data/lib/rjr/tcp_node.rb

@@ -1,5 +1,7 @@
 # RJR TCP Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the TCP protocol
+#
 # Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
@@ -11,14 +13,24 @@ require 'rjr/message'
 
 module RJR
 
-# TCP client node callback interface,
-# send data back to client via established tcp socket.
+# TCP node callback interface, used to invoke json-rpc methods
+# against a remote node via a tcp socket connection previously opened
+#
+# After a node sends a json-rpc request to another, the either node may send
+# additional requests to each other via the socket already established until
+# it is closed on either end
 class TCPNodeCallback
+
+  # TCPNodeCallback initializer
+  # @param [Hash] args the options to create the tcp node callback with
+  # @option args [TCPNodeEndpoint] :endpoint tcp node endpoint used to send/receive messages
+  # @option args [Hash] :headers hash of rjr message headers present in client request when callback is established
   def initialize(args = {})
     @endpoint        = args[:endpoint]
     @message_headers = args[:headers]
   end
 
+  # Implementation of {RJR::NodeCallback#invoke}
   def invoke(callback_method, *data)
     msg = RequestMessage.new :method => callback_method, :args => data, :headers => @message_headers
     # TODO surround w/ begin/rescue block incase of socket errors
@@ -26,9 +38,13 @@ class TCPNodeCallback
   end
 end
 
-# helper class intialized by event machine corresponding to
-# a client or server socket connection
+# @private
+# Helper class intialized by eventmachine encapsulating a socket connection
 class TCPNodeEndpoint < EventMachine::Connection
+
+  # TCPNodeEndpoint intializer
+  #
+  # specify the TCPNode establishing the connection and an optional first message to send
   def initialize(args = {})
     @rjr_node        = args[:rjr_node]
 
@@ -36,6 +52,7 @@ class TCPNodeEndpoint < EventMachine::Connection
     @send_message    = args[:init_message]
   end
 
+  # {EventMachine::Connection#post_init} callback, sends first message if specified
   def post_init
     unless @send_message.nil?
       send_data @send_message.to_s
@@ -43,6 +60,7 @@ class TCPNodeEndpoint < EventMachine::Connection
     end
   end
 
+  # {EventMachine::Connection#receive_data} callback, handle request / response messages
   def receive_data(data)
     if RequestMessage.is_request_message?(data)
       @rjr_node.thread_pool << ThreadPoolJob.new { handle_request(data) }
@@ -54,6 +72,9 @@ class TCPNodeEndpoint < EventMachine::Connection
   end
 
 
+  private
+
+  # Internal helper, handle request message received
   def handle_request(data)
     client_port, client_ip = Socket.unpack_sockaddr_in(get_peername)
     msg    = RequestMessage.new(:message => data, :headers => @rjr_node.message_headers)
@@ -73,6 +94,7 @@ class TCPNodeEndpoint < EventMachine::Connection
     send_data(response.to_s)
   end
 
+  # Internal helper, handle response message received
   def handle_response(data)
     msg    = ResponseMessage.new(:message => data, :headers => @rjr_node.message_headers)
     res = err = nil
@@ -90,7 +112,26 @@ class TCPNodeEndpoint < EventMachine::Connection
   end
 end
 
-# TCP node definition, listen for and invoke json-rpc requests via tcp sockets
+# TCP node definition, listen for and invoke json-rpc requests via TCP sockets
+#
+# Clients should specify the hostname / port when listening for requests and
+# when invoking them.
+#
+# @example Listening for json-rpc requests over tcp
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   RJR::Dispatcher.add_handler('hello') { |name|
+#     "Hello #{name}!"
+#   }
+#
+#   # initialize node, listen, and block
+#   server = RJR::TCPNode.new :node_id => 'server', :host => 'localhost', :port => '7777'
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over tcp
+#   client = RJR::TCPNode.new :node_id => 'client', :host => 'localhost', :port => '8888'
+#   puts client.invoke_request('jsonrpc://localhost:7777', 'hello', 'mo')
+#
 class TCPNode < RJR::Node
   RJR_NODE_TYPE = :tcp
 
@@ -98,8 +139,16 @@ class TCPNode < RJR::Node
   attr_accessor :response_cv
   attr_accessor :responses
 
+  private
+  # Initialize the tcp subsystem
+  def init_node
+  end
+
   public
-  # initialize the node w/ the specified params
+  # TCPNode initializer
+  # @param [Hash] args the options to create the tcp node with
+  # @option args [String] :host the hostname/ip which to listen on
+  # @option args [Integer] :port the port which to listen on
   def initialize(args = {})
      super(args)
      @host      = args[:host]
@@ -114,18 +163,19 @@ class TCPNode < RJR::Node
      @connection_event_handlers = {:closed => [], :error => []}
   end
 
-  # register connection event handler
+  # 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 [TCPNode] 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
 
-  # Initialize the tcp subsystem
-  def init_node
-  end
-
   # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
   def listen
     em_run {
       init_node
@@ -134,6 +184,10 @@ class TCPNode < RJR::Node
   end
 
   # Instructs node to send rpc request, and wait for / return response
+  # @param [String] uri location of node to send request to, should be
+  #   in format of jsonrpc://hostname:port
+  # @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 invoke_request(uri, rpc_method, *args)
     uri = URI.parse(uri)
     host,port = uri.host, uri.port

data/lib/rjr/thread_pool.rb

@@ -3,11 +3,14 @@
 # Copyright (C) 2010-2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
-# Work item to be executed in thread pool
+# Work item to be executed in a thread launched by pool
 class ThreadPoolJob
   attr_accessor :handler
   attr_accessor :params
 
+  # ThreadPoolJob initializer
+  # @param [Array] params arguments to pass to the job when it is invoked
+  # @param [Callable] block handle to callable object corresponding to job to invoke
   def initialize(*params, &block)
     @params = params
     @handler = block
@@ -15,11 +18,15 @@ class ThreadPoolJob
 end
 
 
-# Launches a specified number of threads on instantiation,
-# assigning work to them as it arrives
+# Utility to launches a specified number of threads on instantiation,
+# assigning work to them in order as it arrives.
+#
+# Supports optional timeout which allows the developer to kill and restart
+# threads if a job is taking too long to run.
 class ThreadPool
 
-  # Encapsulate each thread pool thread in object
+  # @private
+  # Helper class to encapsulate each thread pool thread
   class ThreadPoolJobRunner
     attr_accessor :time_started
 
@@ -29,6 +36,10 @@ class ThreadPool
       @thread_lock  = Mutex.new
     end
 
+    # Start thread and pull a work items off the thread pool work queue and execute them.
+    #
+    # This method will return immediately after the worker thread is started but the
+    # thread launched will persist until {#stop} is invoked
     def run
       @thread_lock.synchronize {
         @thread = Thread.new {
@@ -49,6 +60,7 @@ class ThreadPool
       }
     end
 
+    # Return boolean indicating if worker thread is running or not
     def running?
       res = nil
       @thread_lock.synchronize{
@@ -57,7 +69,8 @@ class ThreadPool
       res
     end
 
-    # should not invoke after stop is called
+    # Return boolean indicating if worker thread run time has exceeded timeout
+    # Should not invoke after stop is called
     def check_timeout(timeout)
       @timeout_lock.synchronize {
         if !@time_started.nil? && Time.now - @time_started > timeout
@@ -67,6 +80,7 @@ class ThreadPool
       }
     end
 
+    # Stop the worker thread being executed
     def stop
       @thread_lock.synchronize {
         if @thread.alive?
@@ -77,6 +91,7 @@ class ThreadPool
       }
     end
 
+    # Block until the worker thread is finished
     def join
       @thread_lock.synchronize {
         @thread.join unless @thread.nil?
@@ -85,6 +100,9 @@ class ThreadPool
   end
 
   # Create a thread pool with a specified number of threads
+  # @param [Integer] num_threads the number of worker threads to create
+  # @param [Hash] args optional arguments to initialize thread pool with
+  # @option args [Integer] :timeout optional timeout to use to kill long running worker jobs
   def initialize(num_threads, args = {})
     @num_threads = num_threads
     @timeout     = args[:timeout]
@@ -116,32 +134,37 @@ class ThreadPool
     end
   end
 
+  # Return boolean indicated if thread pool is running.
+  #
+  # If at least one worker thread isn't terminated, the pool is still considered running
   def running?
     !terminate && (@timeout.nil? || (!@timeout_thread.nil? && @timeout_thread.status)) &&
     @job_runners.all? { |r| r.running? }
   end
 
-  # terminate reader
+  # Return boolean indicating if the thread pool should be terminated
   def terminate
     @terminate_lock.synchronize { @terminate }
   end
 
-  # terminate setter
+  # Instruct thread pool to terminate
+  # @param [Boolean] val true/false indicating if thread pool should terminate
   def terminate=(val)
     @terminate_lock.synchronize { @terminate = val }
   end
 
   # Add work to the pool
+  # @param [ThreadPoolJob] work job to execute in first available thread
   def <<(work)
     @work_queue.push work
   end
 
-  # Return the next job queued up
+  # Return the next job queued up and remove it from the queue
   def next_job
     @work_queue.pop
   end
 
-  # Terminate the thread pool
+  # Terminate the thread pool, stopping all worker threads
   def stop
     terminate = true
     unless @timout_thread.nil?
@@ -153,6 +176,7 @@ class ThreadPool
     @job_runners_lock.synchronize { @job_runners.each { |jr| jr.stop } }
   end
 
+  # Block until all worker threads have finished executing
   def join
     @job_runners_lock.synchronize { @job_runners.each { |jr| jr.join } }
   end

data/lib/rjr/web_node.rb

@@ -1,5 +1,10 @@
 # RJR WWW Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the HTTP protocol
+#
+# The web node does not support callbacks at the moment, though at some point we may
+# allow a client to specify an optional webserver to send callback requests to. (TODO)
+#
 # Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
@@ -16,8 +21,8 @@ require 'rjr/message'
 
 module RJR
 
-# Web client node callback interface,
-# currently does nothing as web connections aren't persistant
+# Web node callback interface, *note* callbacks are not supported on the web
+# node and thus this currently does nothing
 class WebNodeCallback
   def initialize()
   end
@@ -26,16 +31,31 @@ class WebNodeCallback
   end
 end
 
-# Web node definition, listen for and invoke json-rpc requests via web requests
+# @private
+# Helper class intialized by eventmachine encapsulating a http connection
 class WebRequestHandler < EventMachine::Connection
   include EventMachine::HttpServer
 
   RJR_NODE_TYPE = :web
 
+  # WebRequestHandler initializer.
+  #
+  # specify the WebNode establishing the connection
   def initialize(*args)
     @web_node = args[0]
   end
 
+  # {EventMachine::Connection#process_http_request} callback, handle request messages
+  def process_http_request
+    # TODO support http protocols other than POST
+    msg = @http_post_content.nil? ? '' : @http_post_content
+    #@thread_pool << ThreadPoolJob.new { handle_request(msg) }
+    handle_request(msg)
+  end
+
+  private
+
+  # Internal helper, handle request message received
   def handle_request(message)
     msg    = nil
     result = nil
@@ -66,38 +86,66 @@ class WebRequestHandler < EventMachine::Connection
     resp.content_type "application/json"
     resp.send_response
   end
+end
 
-  def process_http_request
-    # TODO support http protocols other than POST
-    msg = @http_post_content.nil? ? '' : @http_post_content
-    #@thread_pool << ThreadPoolJob.new { handle_request(msg) }
-    handle_request(msg)
+# Web node definition, listen for and invoke json-rpc requests via web requests
+#
+# Clients should specify the hostname / port when listening for requests and
+# when invoking them.
+#
+# *note* the RJR javascript client also supports sending / receiving json-rpc
+# messages over http
+#
+# @example Listening for json-rpc requests over tcp
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   RJR::Dispatcher.add_handler('hello') { |name|
+#     "Hello #{name}!"
+#   }
+#
+#   # initialize node, listen, and block
+#   server = RJR::WebNode.new :node_id => 'server', :host => 'localhost', :port => '7777'
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over http using rjr
+#   client = RJR::WebNode.new :node_id => 'client'
+#   puts client.invoke_request('http://localhost:7777', 'hello', 'mo')
+#
+# @example Invoking json-rpc requests over http using curl
+#   $ curl -X POST http://localhost:7777 -d '{"jsonrpc":"2.0","method":"hello","params":["mo"],"id":"123"}'
+#   > {"jsonrpc":"2.0","id":"123","result":"Hello mo!"}
+#
+class WebNode < RJR::Node
+  private
+  # Initialize the web subsystem
+  def init_node
   end
 
-  #def receive_data(data)
-  #  puts "~~~~ #{data}"
-  #end
-end
+  public
 
-class WebNode < RJR::Node
-  # initialize the node w/ the specified params
+  # TCPNode initializer
+  # @param [Hash] args the options to create the tcp node with
+  # @option args [String] :host the hostname/ip which to listen on
+  # @option args [Integer] :port the port which to listen on
   def initialize(args = {})
      super(args)
      @host      = args[:host]
      @port      = args[:port]
   end
 
-  # Initialize the web subsystem
-  def init_node
-  end
-
-  # register connection event handler,
-  # since web node connections aren't persistant, we don't do anything here
+  # Register connection event handler,
+  #
+  # *note* Since web node connections aren't persistant, we don't 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?
   end
 
   # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
   def listen
     em_run do
       init_node
@@ -106,6 +154,10 @@ class WebNode < RJR::Node
   end
 
   # Instructs node to send rpc request, and wait for / return response
+  # @param [String] uri location of node to send request to, should be
+  #   in format of http://hostname:port
+  # @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 invoke_request(uri, rpc_method, *args)
     init_node
     message = RequestMessage.new :method => rpc_method,