rjr 0.12.2 → 0.15.1

data/lib/rjr/nodes/easy.rb

@@ -0,0 +1,159 @@
+# RJR Easy Node
+#
+# Implements the RJR::Node client interface to
+# issue JSON-RPC requests over a variety of protocols
+#
+# Copyright (C) 2013 Mohammed Morsi <mo@morsi.org>
+# Licensed under the Apache License, Version 2.0
+
+require 'rjr/nodes/tcp'
+require 'rjr/nodes/ws'
+require 'rjr/nodes/web'
+require 'rjr/nodes/amqp'
+require 'rjr/nodes/multi'
+require 'rjr/node'
+
+module RJR
+module Nodes
+
+# Easy node definition.
+#
+# Clients should specify the transports that they would like to use
+# and their relevant config upon instantating this call. After which
+# invocations and notifications will be routed via the correct transport
+# depending on the format of the destination.
+#
+# All nodes managed locally will share the same dispatcher so that json-rpc methods
+# only need to be registered once, with the multi-node itself.
+#
+# @example invoking requests via multiple protocols
+#   easy = RJR::Nodes::Easy.new :tcp  => { :host   => 'localhost', :port => 8999 },
+#                               :amqp => { :broker => 'localhost' }
+#
+#   easy.invoke 'tcp://localhost:9000/', 'hello world'
+#   # => sent via tcp
+#
+#   easy.notify 'dest-queue', 'hello world'
+#   # => sent via amqp
+#
+class Easy < RJR::Node
+  private
+
+  # Internal helper, retrieved the registered node type depending on
+  # the dst. If matching node type can't be found, nil is returned
+  def get_node(dst)
+    type = nil
+    if dst.is_a?(String)
+      if /tcp:\/\/.*/      =~ dst ||
+         /jsonrpc:\/\/.*/  =~ dst ||
+         /json-rpc:\/\/.*/ =~ dst
+          type = RJR::Nodes::TCP
+
+      elsif /ws:\/\/.*/    =~ dst
+        type = RJR::Nodes::WS
+
+      elsif /http:\/\/.*/   =~ dst
+        type = RJR::Nodes::Web
+
+      elsif /.*-queue$/   =~ dst
+        type = RJR::Nodes::AMQP
+
+      # else # TODO
+      # type = RJR::Nodes::Local
+
+      end
+    end
+
+    return @multi_node.nodes.find { |n| n.is_a?(type) } unless type.nil?
+    nil
+  end
+
+  public
+
+  # Easy Node initializer
+  # @param [Hash] args the options to create the node with
+  # @option args [Hash] :amqp options to create the amqp node with
+  # @option args [Hash] :ws options to create the ws node with
+  # @option args [Hash] :tcp options to create the ws node with
+  # @option args [Hash] :web options to create the web node with
+  def initialize(args = {})
+     super(args)
+
+     nodes = []
+     args.keys.each { |n|
+       node = 
+       case n
+       when :amqp then
+         RJR::Nodes::AMQP.new  args[:amqp].merge(args)
+       when :ws then
+         RJR::Nodes::WS.new    args[:ws].merge(args)
+       when :tcp then
+         RJR::Nodes::TCP.new   args[:tcp].merge(args)
+       when :web then
+         RJR::Nodes::Web.new   args[:web].merge(args)
+       end
+
+       if node
+         nodes << node
+       end
+     }
+
+     @multi_node = RJR::Nodes::Multi.new :nodes => nodes
+     @dispatcher = @multi_node.dispatcher
+  end
+
+  # Send data using specified connection
+  #
+  # Implementation of {RJR::Node#send_msg}
+  def send_msg(data, connection)
+  # TODO
+  end
+
+  # Instruct Nodes to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
+  def listen
+    @multi_node.listen
+  end
+
+  # Instructs node to send rpc request, and wait for and return response.
+  #
+  # Implementation of {RJR::Node#invoke}
+  #
+  # @param [String] dst destination 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(dst, rpc_method, *args)
+    n = get_node(dst)
+    # TODO raise exception if n.nil?
+    n.invoke dst, rpc_method, *args
+  end
+
+  # Instructs node to send rpc notification (immadiately returns / no response is generated)
+  #
+  # Implementation of {RJR::Node#notify}
+  #
+  # @param [String] dst destination to send notification 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
+  def notify(dst, rpc_method, *args)
+    n = get_node(dst)
+    n.notify dst, rpc_method, *args
+  end
+
+  # Stop node on the specified signal
+  #
+  # @param [Singnal] signal signal to stop the node on
+  # @return self
+  def stop_on(signal)
+    Signal.trap(signal) {
+      @multi_node.stop
+    }
+    self
+  end
+end
+
+end # module Nodes
+end # module RJR

data/lib/rjr/nodes/local.rb

@@ -0,0 +1,118 @@
+# RJR Local Endpoint
+#
+# Implements the RJR::Node interface to satisty JSON-RPC requests via local method calls
+#
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
+# Licensed under the Apache License, Version 2.0
+
+require 'rjr/node'
+require 'rjr/message'
+
+module RJR
+module Nodes
+
+# 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.
+#
+# *Note* this only dispatches to the methods defined on the local dispatcher!
+#
+# If you have two local nodes, they will have seperate dispatchers unless you
+# assign them the same object (eg node2.dispatcher = node1.dispatcher or
+# node2 = new RJR::Nodes::Local.new(:dispatcher :=> node1.dispatcher))
+#
+# @example Listening for and dispatching json-rpc requests locally
+#   # initialize node
+#   node = RJR::LocalNode.new :node_id => 'node'
+#
+#   node.dispatcher.handle('hello') do |name|
+#     @rjr_node_type == :local ? "Hello superuser #{name}" : "Hello #{name}!"
+#   end
+#
+#   # invoke request
+#   node.invoke('hello', 'mo')
+#
+class Local < RJR::Node
+  RJR_NODE_TYPE = :local
+
+  # allows clients to override the node type for the local node
+  attr_accessor :node_type
+
+  # LocalNode initializer
+  # @param [Hash] args the options to create the local node with
+  def initialize(args = {})
+     super(args)
+     @node_type = RJR_NODE_TYPE
+  end
+
+  # Send data using specified connection.
+  #
+  # Simply dispatch local notification.
+  #
+  # Implementation of {RJR::Node#send_msg}
+  def send_msg(msg, connection)
+    # ignore response message
+    unless msg.is_a?(ResponseMessage)
+      handle_request(msg, true, nil)
+    end
+  end
+
+  # Instruct Nodes to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
+  def listen
+    # do nothing
+    self
+  end
+
+  # Instructs node to send rpc request, and wait for and return response
+  #
+  # Implementation of {RJR::Node#invoke}
+  #
+  # If strictly confirming to other nodes, this would use event machine to launch
+  # a thread pool job to dispatch request and block on result.
+  # Optimized for performance reasons but recognize that the semantics of using
+  # the local node will be somewhat different.
+  #
+  # @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 with
+  # @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(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).to_s
+    res = handle_request(message, false, nil)
+    return @dispatcher.handle_response(res.result)
+  end
+
+  # Instructs node to send rpc notification (immediately returns / no response is generated)
+  #
+  # Implementation of {RJR::Node#notify}
+  #
+  # Same performance comment as invoke_request above
+  #
+  # @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 notify(rpc_method, *args)
+    # TODO run in thread & immediately return?
+    begin
+      0.upto(args.size).each { |i| args[i] = args[i].to_s if args[i].is_a?(Symbol) }
+      message = NotificationMessage.new(:method => rpc_method,
+                                        :args   => args,
+                                        :headers => @message_headers).to_s
+      handle_request(message, true, nil)
+    rescue
+    end
+    nil
+  end
+
+
+end # class Local
+
+end # module Nodes
+end # module RJR

data/lib/rjr/{missing_node.rb → nodes/missing.rb}

@@ -3,15 +3,17 @@
 # Provides a entity able to be associated with a rjr endpoint
 # if the corresponding node cannot be loaded for whatever reason
 #
-# Copyright (C) 2012 Mohammed Morsi <mo@morsi.org>
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
 # Licensed under the Apache License, Version 2.0
 
 require 'rjr/node'
 
 module RJR
-class MissingNode < RJR::Node
+module Nodes
+class Missing < RJR::Node
   def method_missing(method_id, *args, &bl)
     raise "rjr node #{node_id} is missing a dependency - cannot invoke #{method_id}"
   end
 end
 end
+end

data/lib/rjr/nodes/multi.rb

@@ -0,0 +1,79 @@
+# RJR Multi Node
+#
+# Implements the RJR::Node server interface to satisty
+# JSON-RPC requests over multiple protocols
+#
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
+# Licensed under the Apache License, Version 2.0
+
+require 'rjr/node'
+
+module RJR
+module Nodes
+
+# Multiple node definition, allows a developer to easily multiplex transport
+# mechanisms to serve JSON-RPC requests over.
+#
+# All nodes used locally will share the same dispatcher so that json-rpc methods
+# only need to be registered once, with the multi-node itself.
+#
+# This node does not support client operations (eg send_msg, invoke, and notify)
+#
+# @example Listening for json-rpc requests over amqp, tcp, http, and websockets
+#   # instantiate worker nodes
+#   amqp_server = RJR::Nodes::AMQP.new :node_id => 'amqp_server', :broker => 'localhost'
+#   tcp_server  = RJR::Nodes::TCP.new :node_id => 'tcp_server',  :host => 'localhost', :port => '7777'
+#   web_server  = RJR::Nodes::Web.new :node_id => 'tcp_server',  :host => 'localhost', :port => '80'
+#   ws_server   = RJR::Nodes::WS.new :node_id => 'tcp_server',  :host => 'localhost', :port => '8080'
+#
+#   # instantiate multi node
+#   server = RJR::Nodes::Multi.new :node_id => 'server',
+#                                  :nodes   => [amqp_server, tcp_server, web_server, ws_server]
+#
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   server.dispatcher.handle('hello') do |name|
+#     # optionally use @rjr_node_type to handle different transport types
+#     "Hello #{name}!"
+#   end
+#
+#   server.listen
+#   server.join
+#
+#   # invoke requests as you normally would via any protocol
+#
+class Multi < RJR::Node
+  # Return the nodes
+  attr_reader :nodes
+
+  # 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].each { |n|
+      self << n
+    } if args[:nodes]
+  end
+
+  # Add node to multinode
+  # @param [RJR::Node] node the node to add
+  def <<(node)
+    node.dispatcher = @dispatcher
+    @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
+    }
+    self
+  end
+end
+
+end # module NODES
+end # module RJR

data/lib/rjr/nodes/tcp.rb

@@ -0,0 +1,211 @@
+# RJR TCP Node
+#
+# Implements the RJR::Node interface to satisty JSON-RPC requests over the TCP protocol
+#
+# Copyright (C) 2012-2013 Mohammed Morsi <mo@morsi.org>
+# Licensed under the Apache License, Version 2.0
+
+require 'uri'
+require 'thread'
+require 'eventmachine'
+
+require 'rjr/node'
+require 'rjr/message'
+
+module RJR
+module Nodes
+
+# @private
+# Helper class intialized by eventmachine encapsulating a socket connection
+class TCPConnection < EventMachine::Connection
+  attr_reader :host
+  attr_reader :port
+
+  # TCPConnection intializer
+  #
+  # Specify the TCP Node establishing the connection and
+  # optionaly remote host/port which this connection is connected to
+  def initialize(args = {})
+    @rjr_node  = args[:rjr_node]
+    @host      = args[:host]
+    @port      = args[:port]
+
+    @send_lock = Mutex.new
+    @data      = ""
+  end
+
+  # {EventMachine::Connection#receive_data} callback, handle request / response messages
+  def receive_data(data)
+    # a large json-rpc message may be split over multiple packets
+    #   (invocations of receive_data)
+    # and multiple messages may be concatinated into one packet
+    @data += data
+    while extracted = MessageUtil.retrieve_json(@data)
+      msg, @data = *extracted
+      @rjr_node.send(:handle_message, msg, self) # XXX private method
+    end
+  end
+
+  # Send data safely using local connection
+  def send_msg(data)
+    @send_lock.synchronize{
+      send_data(data)
+    }
+  end
+
+end
+
+# 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
+#   # initialize node
+#   server = RJR::Nodes::TCP.new :node_id => 'server', :host => 'localhost', :port => '7777'
+#
+#   # register rjr dispatchers (see RJR::Dispatcher)
+#   server.dispatcher.handle('hello') { |name|
+#     "Hello #{name}!"
+#   }
+#
+#   # listen and block
+#   server.listen
+#   server.join
+#
+# @example Invoking json-rpc requests over tcp
+#   client = RJR::Nodes::TCP.new :node_id => 'client', :host => 'localhost', :port => '8888'
+#   puts client.invoke('jsonrpc://localhost:7777', 'hello', 'mo')
+#
+class TCP < RJR::Node
+  RJR_NODE_TYPE = :tcp
+
+  attr_accessor :connections
+
+  private
+  # Internal helper, initialize new client
+  def init_client(args={}, &on_init)
+    host,port = args[:host], args[:port]
+    connection = nil
+    @connections_lock.synchronize {
+      connection = @connections.find { |c|
+                     port == c.port && host == c.host
+                   }
+      if connection.nil?
+        connection =
+          EventMachine::connect host, port,
+                      TCPConnection, args
+        @connections << connection
+      end
+    }
+    on_init.call(connection) # TODO move to tcpnode event ?
+  end
+
+  public
+
+  # TCP 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]
+
+     @connections = []
+     @connections_lock = Mutex.new
+  end
+
+  # Send data using specified connection
+  #
+  # Implementation of {RJR::Node#send_msg}
+  def send_msg(data, connection)
+    connection.send_msg(data)
+  end
+
+  # Instruct Node to start listening for and dispatching rpc requests
+  #
+  # Implementation of {RJR::Node#listen}
+  def listen
+    @em.schedule {
+      @em.start_server @host, @port, TCPConnection, { :rjr_node => self }
+    }
+    self
+  end
+
+  # Instructs node to send rpc request, and wait for / return response.
+  #
+  # Implementation of {RJR::Node#invoke}
+  #
+  # Do not invoke directly from em event loop or callback as will block the message
+  # subscription used to receive responses
+  #
+  # @param [String] uri location of node to send request to, should be
+  #   in format of jsonrpc://hostname:port or tcp://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(uri, rpc_method, *args)
+    uri = URI.parse(uri)
+    host,port = uri.host, uri.port
+
+    message = RequestMessage.new :method => rpc_method,
+                                 :args   => args,
+                                 :headers => @message_headers
+    connection = nil
+    @em.schedule {
+      init_client(:host => host, :port => port,
+                  :rjr_node => self) { |c|
+        connection = c
+        c.send_msg message.to_s
+      }
+    }
+
+    # TODO optional timeout for response ?
+    result = wait_for_result(message)
+
+    if result.size > 2
+      raise Exception, result[2]
+    end
+    return result[1]
+  end
+
+  # Instructs node to send rpc notification (immadiately returns / no response is generated)
+  #
+  # Implementation of {RJR::Node#notify}
+  #
+  # @param [String] uri location of node to send notification 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 notify(uri, rpc_method, *args)
+    # will block until message is published
+    published_l = Mutex.new
+    published_c = ConditionVariable.new
+
+    uri = URI.parse(uri)
+    host,port = uri.host, uri.port
+
+    invoked = false
+    conn    = nil
+    message = NotificationMessage.new :method => rpc_method,
+                                      :args   => args,
+                                      :headers => @message_headers
+    @em.schedule {
+      init_client(:host => host, :port => port,
+                  :rjr_node => self) { |c|
+        conn = c
+        c.send_msg message.to_s
+        # XXX, this should be invoked only when we are sure event
+        # machine sent message. Shouldn't pose a problem unless event
+        # machine is killed immediately after
+        published_l.synchronize { invoked = true ; published_c.signal }
+      }
+    }
+    published_l.synchronize { published_c.wait published_l unless invoked }
+    #sleep 0.01 until conn.get_outbound_data_size == 0
+    nil
+  end
+end
+
+end # module Nodes
+end # module RJR