rjr 0.7.0 → 0.8.0

data/lib/rjr/ws_node.rb

@@ -1,11 +1,10 @@
 # RJR WebSockets Endpoint
 #
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the websockets 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 'em-websocket'
 require 'rjr/web_socket'
 
@@ -14,14 +13,23 @@ require 'rjr/message'
 
 module RJR
 
-# Web Socket client node callback interface,
-# send data back to client via established web socket.
+# Web Socket node callback interface, used to invoke json-rpc methods
+# against a remote node via a web socket 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 socket already established until
+# it is closed on either end
 class WSNodeCallback
+  # WSNodeCallback initializer
+  # @param [Hash] args the options to create the websocket node callback with
+  # @option args [Socket] :socket socket connection 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 = {})
     @socket    = args[:socket]
     @message_headers = args[:headers]
   end
 
+  # Implementation of {RJR::NodeCallback#invoke}
   def invoke(callback_method, *data)
     #msg = CallbackMessage.new(:data => data)
     msg = RequestMessage.new :method => callback_method, :args => data, :headers => @message_headers
@@ -31,11 +39,37 @@ class WSNodeCallback
   end
 end
 
-# Web node definition, listen for and invoke json-rpc requests via web sockets
+# Web socket node definition, listen for and invoke json-rpc requests via web sockets
+#
+# Clients should specify the hostname / port when listening for and invoking requests.
+#
+# *note* the RJR javascript client also supports sending / receiving json-rpc
+# messages over web sockets
+#
+# @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::WSNode.new :node_id => 'server', :host => 'localhost', :port => '7777'
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over web sockets using rjr
+#   client = RJR::WsNode.new :node_id => 'client'
+#   puts client.invoke_request('ws://localhost:7777', 'hello', 'mo')
+#
 class WSNode < RJR::Node
   RJR_NODE_TYPE = :websockets
 
   private
+  # Initialize the ws subsystem
+  def init_node
+  end
+
+  # Internal helper, handle request message received
   def handle_request(socket, message)
     client_port, client_ip = Socket.unpack_sockaddr_in(socket.get_peername)
     msg    = RequestMessage.new(:message => message, :headers => @message_headers)
@@ -56,7 +90,10 @@ class WSNode < RJR::Node
   end
 
   public
-  # initialize the node w/ the specified params
+  # WSNode initializer
+  # @param [Hash] args the options to create the web socket 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]
@@ -65,18 +102,19 @@ class WSNode < 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 [WSNode] 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 ws subsystem
-  def init_node
-  end
-
   # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
   def listen
     em_run do
       init_node
@@ -100,6 +138,10 @@ class WSNode < 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 ws://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,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rjr
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -27,6 +27,38 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby Json Rpc library
 email: mo@morsi.org
 executables:
@@ -61,7 +93,7 @@ files:
 - specs/message_spec.rb
 - LICENSE
 - Rakefile
-- README.rdoc
+- README.md
 - bin/rjr-server
 homepage: http://github.com/movitto/rjr
 licenses: []
@@ -88,3 +120,4 @@ signing_key:
 specification_version: 3
 summary: JSON RPC server and client library over amqp, websockets, http, etc
 test_files: []
+has_rdoc: 

data/README.rdoc

@@ -1,73 +0,0 @@
-== RJR - Ruby Json Rpc Library
-
-Copyright (C) 2012 Mo Morsi <mo@morsi.org>
-
-RJR is made available under the GNU AFFERO GENERAL PUBLIC LICENSE
-as published by the Free Software Foundation, either version 3
-of the License, or (at your option) any later version.
-
-=== 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>
-
-Generate documentation via
-  rake rdoc
-
-Also see specs for detailed usage.
-
-=== Authors
- Mo Morsi <mo@morsi.org>