rjr 0.5.3

data/README.rdoc

@@ -0,0 +1,73 @@
+== 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>

data/Rakefile

@@ -0,0 +1,64 @@
+# rjr project Rakefile
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+require 'rdoc/task'
+require "rspec/core/rake_task"
+require 'rubygems/package_task'
+
+
+GEM_NAME="rjr"
+PKG_VERSION='0.5.3'
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'specs/**/*_spec.rb'
+  spec.rspec_opts = ['--backtrace']
+end
+
+desc "run javascript tests"
+task :test_js do
+  ENV['RUBYLIB'] = "lib"
+  puts "Launching js test runner"
+  system("tests/js/runner")
+end
+
+desc "run integration/stress tests"
+task :integration do
+  ENV['RUBYLIB'] = "lib"
+  puts "Launching integration test runner"
+  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")
+end
+
+PKG_FILES = FileList['lib/**/*.rb', 
+  'LICENSE', 'Rakefile', 'README.rdoc', 'spec/**/*.rb' ]
+
+SPEC = Gem::Specification.new do |s|
+    s.name = GEM_NAME
+    s.version = PKG_VERSION
+    s.files = PKG_FILES
+    s.executables << 'rjr-server'
+
+    s.required_ruby_version = '>= 1.8.1'
+    s.required_rubygems_version = Gem::Requirement.new(">= 1.3.3")
+    s.add_development_dependency('rspec', '~> 1.3.0')
+
+    s.author = "Mohammed Morsi"
+    s.email = "mo@morsi.org"
+    s.date = %q{2012-04-25}
+    s.description = %q{Ruby Json Rpc library}
+    s.summary = %q{JSON RPC server and client library over amqp, websockets}
+    s.homepage = %q{http://morsi.org/projects/rjr}
+end
+
+Gem::PackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+    pkg.need_zip = true
+end

data/bin/rjr-server

@@ -0,0 +1,51 @@
+#!/usr/bin/ruby
+# A rjr server executable
+# Executable to launch registered rjr methods 
+#
+# Flags:
+#  -h --help
+#
+# Copyright (C) 2011 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+require 'rubygems'
+require 'optparse'
+require 'rjr'
+
+######################
+
+
+def main()
+  # setup cmd line options
+  opts = OptionParser.new do |opts|
+    opts.on("-h", "--help", "Print help message") do
+       puts opts
+       exit
+    end
+  end
+
+  # parse cmd line
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::InvalidOption
+    puts opts
+    exit
+  end
+
+  amqp_node = RJR::AMQPNode.new :node_id => 'rjr', :broker => 'localhost'
+  ws_node   = RJR::WSNode.new   :node_id => 'rjr', :host   => 'localhost', :port => 8080
+  www_node  = RJR::WebNode.new  :node_id => 'rjr', :host   => 'localhost', :port => 8888
+
+  RJR::Dispatcher.add_handler('hello') { |msg|
+    #raise Exception.new("foobar")
+    puts "hello #{msg}"
+    "world"
+  }
+
+  rjr_node = RJR::MultiNode.new :nodes => [amqp_node, ws_node, www_node]
+
+  rjr_node.listen
+  rjr_node.terminate # TODO run in signal handler
+end
+
+main()

data/lib/rjr/amqp_node.rb

@@ -0,0 +1,164 @@
+# RJR AMQP Endpoint
+#
+# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# 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'
+require 'rjr/message'
+
+module RJR
+
+# AMQP client node callback interface,
+# send data back to client via AMQP.
+class AMQPNodeCallback
+  def initialize(args = {})
+    @exchange    = args[:exchange]
+    @exchange_lock = args[:exchange_lock]
+    @destination = args[:destination]
+    @message_headers = args[:headers]
+    @disconnected = false
+
+    @exchange_lock.synchronize{
+      # FIXME should disconnect all callbacks on_return
+      @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
+      end
+    }
+  end
+
+  def invoke(callback_method, *data)
+    msg = RequestMessage.new :method => callback_method, :args => data, :headers => @message_headers
+    raise RJR::Errors::ConnectionError.new("client unreachable") if @disconnected
+    @exchange_lock.synchronize{
+      @exchange.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
+  RJR_NODE_TYPE = :amqp
+
+
+  private
+  def handle_message(metadata, msg)
+    if RequestMessage.is_request_message?(msg)
+      reply_to = metadata.reply_to
+
+      # TODO should delete handler threads as they complete & should handle timeout
+      @thread_pool << ThreadPoolJob.new { handle_request(reply_to, msg) }
+
+    elsif ResponseMessage.is_response_message?(msg)
+      # TODO test message, make sure it is a response message
+      msg    = ResponseMessage.new(:message => msg, :headers => @message_headers)
+      lock   = @message_locks[msg.msg_id]
+      if lock
+        headers = @message_headers.merge(msg.headers)
+        res = Dispatcher.handle_response(msg.result)
+        lock << res
+        lock[0].synchronize { lock[1].signal }
+      end
+
+    end
+  end
+
+  def handle_request(reply_to, message)
+    msg    = RequestMessage.new(:message => message, :headers => @message_headers)
+    headers = @message_headers.merge(msg.headers) # append request message headers
+    result = Dispatcher.dispatch_request(msg.jr_method,
+                                         :method_args => msg.jr_args,
+                                         :headers => headers,
+                                         :rjr_node_id   => @node_id,
+                                         :rjr_node_type => RJR_NODE_TYPE,
+                                         :rjr_callback =>
+                                           AMQPNodeCallback.new(:exchange => @exchange,
+                                                                :exchange_lock => @exchange_lock,
+                                                                :destination => reply_to,
+                                                                :headers => headers))
+    response = ResponseMessage.new(:id => msg.msg_id, :result => result, :headers => headers)
+    @exchange_lock.synchronize{
+      @exchange.publish(response.to_s, :routing_key => reply_to)
+    }
+  end
+
+  public
+
+  # initialize the node w/ the specified params
+  def initialize(args = {})
+     super(args)
+     @broker    = args[:broker]
+
+     # tuple of message ids to locks/condition variables for the responses
+     # of those messages with optional result response
+     @message_locks = {}
+  end
+
+  # Initialize the amqp subsystem
+  def init_node
+     @conn = AMQP.connect(:host => @broker)
+     @conn.on_tcp_connection_failure { puts "OTCF #{@node_id}" }
+
+     ### 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
+     @exchange_lock = Mutex.new
+  end
+
+  # Instruct Node to start listening for and dispatching rpc requests
+  def listen
+    em_run do
+      init_node
+
+      # start receiving messages
+      @queue.subscribe do |metadata, msg|
+         handle_message(metadata, msg)
+      end
+    end
+  end
+
+  # Instructs node to send rpc request, and wait for / return response
+  def invoke_request(routing_key, rpc_method, *args)
+    req_mutex = Mutex.new
+    req_cv = ConditionVariable.new
+
+    message = RequestMessage.new :method => rpc_method,
+                                 :args   => args,
+                                 :headers => @message_headers
+    em_run do
+      init_node
+
+      @message_locks[message.msg_id] = [req_mutex, req_cv]
+
+      # begin listening for result
+      @queue.subscribe do |metadata, msg|
+        handle_message(metadata, msg)
+      end
+
+      @exchange_lock.synchronize{
+        @exchange.publish(message.to_s, :routing_key => routing_key, :reply_to => @queue_name)
+      }
+    end
+
+    ## wait for result
+    # TODO - make this optional, eg a non-blocking operation mode
+    #        (allowing event handler registration to be run on success / fail / etc)
+    req_mutex.synchronize { req_cv.wait(req_mutex) }
+    result = @message_locks[message.msg_id][2] 
+    @message_locks.delete(message.msg_id)
+    self.stop
+    self.join unless self.em_running?
+    return result
+  end
+
+end
+end

data/lib/rjr/common.rb

@@ -0,0 +1,60 @@
+# RJR Utility Methods
+#
+# Copyright (C) 2011 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+require 'logger'
+
+module RJR
+
+# Logger helper class
+class Logger
+  private
+    def self._instantiate_logger
+       unless defined? @@logger
+         @@logger = ::Logger.new(STDOUT)
+         @@logger.level = ::Logger::FATAL
+       end 
+    end 
+
+  public
+
+    def self.method_missing(method_id, *args)
+       _instantiate_logger
+       @@logger.send(method_id, args)
+    end 
+
+    def self.logger
+       _instantiate_logger
+       @@logger
+    end
+
+    def self.log_level=(level)
+      _instantiate_logger
+      @@logger.level = level
+    end
+end
+
+end # module RJR
+
+# http://blog.jayfields.com/2006/09/ruby-instanceexec-aka-instanceeval.html
+class Object
+  module InstanceExecHelper; end
+  include InstanceExecHelper
+  def instance_exec(*args, &block)
+    begin
+      old_critical, Thread.critical = Thread.critical, true
+      n = 0
+      n += 1 while respond_to?(mname="__instance_exec#{n}")
+      InstanceExecHelper.module_eval{ define_method(mname, &block) }
+    ensure
+      Thread.critical = old_critical
+    end
+    begin
+      ret = send(mname, *args)
+    ensure
+      InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+    end
+    ret
+  end
+end

data/lib/rjr/dispatcher.rb

@@ -0,0 +1,169 @@
+# RJR Request / Response Dispatcher
+#
+# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# establish client connection w/ specified args and invoke block w/ 
+# newly created client, returning it after block terminates
+
+require 'rjr/common'
+
+module RJR
+
+class Request
+  attr_accessor :method
+  attr_accessor :method_args
+  attr_accessor :headers
+  attr_accessor :rjr_callback
+  attr_accessor :rjr_node_type
+  attr_accessor :rjr_node_id
+
+  attr_accessor :handler
+
+  def initialize(args = {})
+    @method       = args[:method]
+    @method_args  = args[:method_args]
+    @headers      = args[:headers]
+    @rjr_callback = args[:rjr_callback]
+    @rjr_node_id   = args[:rjr_node_id]
+    @rjr_node_type = args[:rjr_node_type]
+    @handler       = args[:handler]
+  end
+
+  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)
+    RJR::Logger.info "#{@method} request with parameters (#{@method_args.join(',')}) returning #{retval}"
+    return retval
+  end
+end
+
+class Result
+  attr_accessor :success
+  attr_accessor :failed
+  attr_accessor :result
+  attr_accessor :error_code
+  attr_accessor :error_msg
+  attr_accessor :error_class
+
+  def initialize(args = {})
+    @result        = nil
+    @error_code    = nil
+    @error_message = nil
+    @error_class = nil
+
+    if args.has_key?(:result)
+      @success = true
+      @failed  = false
+      @result  = args[:result]
+
+    elsif args.has_key?(:error_code)
+      @success = false
+      @failed  = true
+      @error_code  = args[:error_code]
+      @error_msg   = args[:error_msg]
+      @error_class = args[:error_class]
+
+    end
+  end
+
+  def ==(other)
+    @success == other.success &&
+    @failed  == other.failed  &&
+    @result  == other.result  &&
+    @error_code == other.error_code &&
+    @error_msg  == other.error_msg  &&
+    @error_class == other.error_class
+  end
+
+  def to_s
+    "#{@success} #{@result} #{@error_code} #{@error_msg} #{@error_class}"
+  end
+
+  ######### Specific request types
+
+  def self.invalid_request
+     return Result.new(:error_code => -32600,
+                       :error_msg => '  Invalid Request')
+  end
+
+  def self.method_not_found(name)
+     return Result.new(:error_code => -32602,
+                       :error_msg => "Method '#{name}' not found")
+  end
+
+end
+
+class Handler
+  attr_accessor :method_name
+  attr_accessor :handler_proc
+
+  def initialize(args = {})
+    @method_name          = args[:method]
+    @handler_proc         = args[:handler]
+  end
+
+  def handle(args = {})
+    return Result.method_not_found(args[:missing_name]) if @method_name.nil?
+
+    begin
+      request = Request.new args.merge(:method          => @method_name,
+                                       :handler         => @handler_proc)
+      retval = request.handle
+      return Result.new(:result => retval)
+
+    rescue Exception => e
+      RJR::Logger.warn "Exception Raised in #{method_name} handler #{e}"
+      e.backtrace.each { |b| RJR::Logger.warn b }
+      # TODO store exception class to be raised later
+
+      return Result.new(:error_code => -32000,
+                        :error_msg  => e.to_s,
+                        :error_class => e.class)
+
+    end
+  end
+end
+
+class Dispatcher
+  # clear handlers
+  def self.init_handlers
+    @@handlers = {}
+  end
+
+  # register a handler to the specified method
+  def self.add_handler(method_name, args = {}, &handler)
+    @@handlers  ||= {}
+    @@handlers[method_name] = Handler.new args.merge(:method  => method_name,
+                                                     :handler => handler)
+  end
+
+  # Helper to handle request messages
+  def self.dispatch_request(method_name, args = {})
+     @@handlers  ||= {}
+     handler  = @@handlers[method_name]
+
+     if handler.nil?
+       @@generic_handler ||= Handler.new :method => nil
+       return @@generic_handler.handle(args.merge(:missing_name => method_name))
+     end
+
+     return handler.handle args
+  end
+
+  # Helper to handle response messages
+  def self.handle_response(result)
+     unless result.success
+       #if result.error_class
+       #  TODO needs to be constantized first (see TODO in lib/rjr/message)
+       #  raise result.error_class.new(result.error_msg) unless result.success
+       #else
+         raise Exception, result.error_msg
+       #end
+     end
+     return result.result
+  end
+
+end
+
+end # module RJR

data/lib/rjr/errors.rb

@@ -0,0 +1,21 @@
+# RJR Errors
+#
+# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# establish client connection w/ specified args and invoke block w/ 
+# newly created client, returning it after block terminates
+
+module RJR
+module Errors
+
+def self.const_missing(error_name)  # :nodoc:
+  if error_name.to_s =~ /Error\z/
+    const_set(error_name, Class.new(RuntimeError))
+  else
+    super
+  end
+end
+
+end
+end

data/lib/rjr/local_node.rb

@@ -0,0 +1,65 @@
+# RJR Local Endpoint
+#
+# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# 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
+class LocalNodeCallback
+  def initialize(args = {})
+    @node        = args[:node]
+  end
+
+  def invoke(callback_method, *data)
+    @node.invoke_request(callback_method, *data)
+    # TODO support local_node 'disconnections'
+  end
+end
+
+# Local node definition, listen for and invoke json-rpc
+# requests via local handlers
+class LocalNode < RJR::Node
+  RJR_NODE_TYPE = :local
+
+  # allow clients to override the node type for the local node
+  attr_accessor :node_type
+
+  # initialize the node w/ the specified params
+  def initialize(args = {})
+     super(args)
+     @node_type = RJR_NODE_TYPE
+  end
+
+  # Instruct Node to start listening for and dispatching rpc requests
+  def listen
+    em_run do
+    end
+  end
+
+  # Instructs node to send rpc request, and wait for / return response
+  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,
+                                 :args   => args,
+                                 :headers => @message_headers
+    result = Dispatcher.dispatch_request(rpc_method,
+                                         :method_args => args,
+                                         :headers => @message_headers,
+                                         :rjr_node_id   => @node_id,
+                                         :rjr_node_type => @node_type,
+                                         :rjr_callback =>
+                                           LocalNodeCallback.new(:node => self,
+                                                                 :headers => @message_headers))
+    return Dispatcher.handle_response(result)
+  end
+
+end
+end