arachni-rpc 0.1.3 → 0.2.0

data/lib/arachni/rpc/proxy.rb

@@ -0,0 +1,86 @@
+=begin
+
+    This file is part of the Arachni-RPC project and may be subject to
+    redistribution and commercial restrictions. Please see the Arachni-RPC
+    web site for more information on licensing and terms of use.
+
+=end
+
+module Arachni
+module RPC
+
+# Maps the methods of remote objects to local ones.
+#
+# You start like:
+#
+#     client = Arachni::RPC::Client.new( host: 'localhost', port: 7331 )
+#     bench  = Arachni::RPC::Proxy.new( client, 'bench' )
+#
+# And it allows you to do this:
+#
+#     result = bench.foo( 1, 2, 3 )
+#
+# Instead of:
+#
+#     result = client.call( 'bench.foo', 1, 2, 3 )
+#
+# The server on the other end must have an appropriate handler set, like:
+#
+#     class Bench
+#         def foo( i = 0 )
+#             return i
+#         end
+#     end
+#
+#     server = Arachni::RPC::Server.new( host: 'localhost', port: 7331 )
+#     server.add_handler( 'bench', Bench.new )
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Proxy
+
+    class <<self
+
+        # @param    [Symbol]    method_name
+        #   Method whose response to translate.
+        # @param    [Block]    translator
+        #   Block to be passed the response and return a translated object.
+        def translate( method_name, &translator )
+            define_method method_name do |*args, &b|
+                # For blocking calls.
+                if !b
+                    data = forward( method_name, *args )
+                    return data.rpc_exception? ?
+                        data : translator.call( data, *args )
+                end
+
+                # For non-blocking calls.
+                forward( method_name, *args ) do |data|
+                    b.call( data.rpc_exception? ?
+                                data : translator.call( data, *args ) )
+                end
+            end
+        end
+    end
+
+    # @param    [Client]    client
+    # @param    [String]    handler
+    def initialize( client, handler )
+        @client  = client
+        @handler = handler
+    end
+
+    def forward( sym, *args, &block )
+        @client.call( "#{@handler}.#{sym.to_s}", *args, &block )
+    end
+
+    private
+
+    # Used to provide the illusion of locality for remote methods.
+    def method_missing( *args, &block )
+        forward( *args, &block )
+    end
+
+end
+
+end
+end

data/lib/arachni/rpc/request.rb

@@ -6,67 +6,49 @@
 
 =end
 
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'message' )
+require_relative 'message'
 
 module Arachni
 module RPC
 
-#
 # Represents an RPC request.
 #
-# It's here only for formalization purposes,
-# it's not actually sent over the wire.
-#
-# What is sent is a hash generated by {#prepare_for_tx}.
-# which is in the form of:
+# It's here only for formalization purposes, it's not actually sent over the wire.
 #
+# What is sent is a hash generated by {#prepare_for_tx}. which is in the form of:
 #
-#    {
-#        'message'     => msg, # RPC message in the form of 'handler.method'
-#        'args'        => args, # optional array of arguments for the remote method
-#        'token'       => token, # optional authentication token
-#    }
 #
-# Any client that has SSL support and can serialize a Hash
-# just like the one above can communicate with the RPC server.
+#     {
+#         # RPC message in the form of 'handler.method'.
+#         'message' => msg,
+#         # Optional array of arguments for the remote method.
+#         'args'    => args,
+#         # Optional authentication token.
+#         'token'   => token
+#     }
 #
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# Any client that has SSL support and can serialize a Hash just like the one
+# above can communicate with the RPC server.
 #
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
 class Request < Message
 
-    #
-    # RPC message in the form of 'handler.method'.
-    #
     # @return   [String]
-    #
+    #   RPC message in the form of 'handler.method'.
     attr_accessor :message
 
-    #
-    # Optional array of arguments for the remote method.
-    #
     # @return   [Array]
-    #
+    #   Optional arguments for the remote method.
     attr_accessor :args
 
-    #
-    # Optional authentication token.
-    #
     # @return   [String]
-    #
+    #   Optional authentication token.
     attr_accessor :token
 
-    #
-    # Callback to be invoked on the response.
-    #
     # @return   [Proc]
-    #
+    #   Callback to be invoked on the response.
     attr_accessor :callback
 
-    # @see Message#initialize
-    def initialize( * )
-        super
-    end
-
     private
 
     def transmit?( attr )

data/lib/arachni/rpc/response.rb

@@ -6,60 +6,47 @@
 
 =end
 
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'message' )
-
 module Arachni
 module RPC
 
-#
 # Represents an RPC response.
 #
 # It's here only for formalization purposes, it's not actually sent over the wire.
 #
-# What is sent is a hash generated by {#prepare_for_tx}
-# which is in the form of:
-#
+# What is sent is a hash generated by {#prepare_for_tx} which is in the form of:
 #
 #    {
 #        # result of the RPC call
-#        'obj'       => object
+#        'obj' => object
 #    }
 #
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
-#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
 class Response < Message
 
-    #
-    # Return object of the {Request#message}.
-    #
-    # If there was an exception it will hold a Hash like:
-    #
-    #    {
-    #        "exception" => "Trying to access non-existent object 'blah'.",
-    #        "backtrace" => [
-    #            [0] "/home/zapotek/workspace/arachni-rpc/lib/arachni/rpc/server.rb:285:in `call'",
-    #            [1] "/home/zapotek/workspace/arachni-rpc/lib/arachni/rpc/server.rb:85:in `block in receive_object'",
-    #            [2] "/home/zapotek/.rvm/gems/ruby-1.9.2-p180/gems/eventmachine-1.0.0.beta.3/lib/eventmachine.rb:1009:in `call'",
-    #            [3] "/home/zapotek/.rvm/gems/ruby-1.9.2-p180/gems/eventmachine-1.0.0.beta.3/lib/eventmachine.rb:1009:in `block in spawn_threadpool'"
-    #        ],
-    #             "type" => "InvalidObject"
-    #    }
-    #
-    # For all available exception types look at {Exceptions}.
-    #
     # @return   [Object]
-    #
+    #   Return object of the {Request#message}.
     attr_accessor :obj
 
-    # @see Message#initialize
-    def initialize( * )
-        super
+    # @return   [Hash]
+    #
+    #       {
+    #           "name" => "Trying to access non-existent object 'blah'.",
+    #           "backtrace" => [
+    #               [0] "/home/zapotek/workspace/arachni-rpc/lib/arachni/rpc/server.rb:285:in `call'",
+    #               [1] "/home/zapotek/workspace/arachni-rpc/lib/arachni/rpc/server.rb:85:in `block in receive_object'",
+    #           ],
+    #           "type" => "InvalidObject"
+    #       }
+    #
+    #   For all available exception types look at {Exceptions}.
+    attr_accessor :exception
 
-        @async = false
+    def exception?
+        !!exception
     end
 
     def async?
-        @async
+        !!@async
     end
 
     def async!
@@ -69,10 +56,9 @@ class Response < Message
     private
 
     def transmit?( attr )
-        ![ :@async ].include?( attr )
+        ![:@async].include?( attr )
     end
 
-
 end
 
 end

data/lib/arachni/rpc/server.rb

@@ -0,0 +1,278 @@
+=begin
+
+    This file is part of the Arachni-RPC EM project and may be subject to
+    redistribution and commercial restrictions. Please see the Arachni-RPC EM
+    web site for more information on licensing and terms of use.
+
+=end
+
+require 'set'
+require 'logger'
+
+module Arachni
+module RPC
+
+require_relative 'server/handler'
+
+# RPC server.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Server
+
+    # @return   [String]
+    #   Authentication token.
+    attr_reader :token
+
+    # @return   [Hash]
+    #   Configuration options.
+    attr_reader :opts
+
+    # @return   [Logger]
+    attr_reader :logger
+
+    # Starts the RPC server.
+    #
+    # @example  Example options:
+    #
+    #    {
+    #        :host  => 'localhost',
+    #        :port  => 7331,
+    #
+    #        # optional authentication token, if it doesn't match the one
+    #        # set on the server-side you'll be getting exceptions.
+    #        :token => 'superdupersecret',
+    #
+    #        # optional serializer (defaults to YAML)
+    #        :serializer => Marshal,
+    #
+    #        # In order to enable peer verification one must first provide
+    #        # the following:
+    #        #
+    #        # SSL CA certificate
+    #        :ssl_ca     => cwd + '/../spec/pems/cacert.pem',
+    #        # SSL private key
+    #        :ssl_pkey   => cwd + '/../spec/pems/client/key.pem',
+    #        # SSL certificate
+    #        :ssl_cert   => cwd + '/../spec/pems/client/cert.pem'
+    #    }
+    #
+    # @param    [Hash]  opts
+    # @option   opts    [String]    :host   Hostname/IP address.
+    # @option   opts    [Integer]   :port   Port number.
+    # @option   opts    [String]   :socket   Path to UNIX domain socket.
+    # @option   opts    [String]    :token  Optional authentication token.
+    # @option   opts    [.dump, .load]      :serializer (YAML)
+    #   Serializer to use for message transmission.
+    # @option   opts    [.dump, .load]      :fallback_serializer
+    #   Optional fallback serializer to be used when the primary one fails.
+    # @option   opts    [Integer]   :max_retries
+    #   How many times to retry failed requests.
+    # @option   opts    [String]    :ssl_ca  SSL CA certificate.
+    # @option   opts    [String]    :ssl_pkey  SSL private key.
+    # @option   opts    [String]    :ssl_cert  SSL certificate.
+    def initialize( opts )
+        @opts = opts
+
+        if @opts[:ssl_pkey] && @opts[:ssl_cert]
+            if !File.exist?( @opts[:ssl_pkey] )
+                raise "Could not find private key at: #{@opts[:ssl_pkey]}"
+            end
+
+            if !File.exist?( @opts[:ssl_cert] )
+                raise "Could not find certificate at: #{@opts[:ssl_cert]}"
+            end
+        end
+
+        @token = @opts[:token]
+
+        @logger = ::Logger.new( STDOUT )
+        @logger.level = Logger::INFO
+
+        @host, @port = @opts[:host], @opts[:port]
+        @socket = @opts[:socket]
+
+        if !@socket && !(@host || @port)
+            fail ArgumentError, 'Needs either a :socket or :host and :port options.'
+        end
+
+        @port = @port.to_i
+
+        @reactor = Reactor.global
+
+        clear_handlers
+    end
+
+    # @example
+    #
+    #    server.add_async_check do |method|
+    #        #
+    #        # Must return 'true' for async and 'false' for sync.
+    #        #
+    #        # Very simple check here...
+    #        #
+    #        'async' ==  method.name.to_s.split( '_' )[0]
+    #    end
+    #
+    # @param    [Block]  block
+    #   Block to identify methods that pass their result to a block instead of
+    #   simply returning them (which is the most usual operation of async methods).
+    def add_async_check( &block )
+        @async_checks << block
+    end
+
+    # @example
+    #
+    #    server.add_handler( 'myclass', MyClass.new )
+    #
+    # @param    [String]    name
+    #   Name by which to make the object available over RPC.
+    # @param    [Object]    obj
+    #   Instantiated server object to expose.
+    def add_handler( name, obj )
+        @objects[name]       = obj
+        @methods[name]       = Set.new
+        @async_methods[name] = Set.new
+
+        obj.class.public_instance_methods( false ).each do |method|
+            @methods[name]       << method.to_s
+            @async_methods[name] << method.to_s if async_check( obj.method( method ) )
+        end
+    end
+
+    # Clears all handlers and their associated information like methods and
+    # async check blocks.
+    #
+    # @see #add_handler
+    # @see #add_async_check
+    def clear_handlers
+        @objects = {}
+        @methods = {}
+
+        @async_checks  = []
+        @async_methods = {}
+    end
+
+    # Runs the server and blocks while `Arachni::Reactor` is running.
+    def run
+        @reactor.run { start }
+    end
+
+    # Starts the server but does not block.
+    def start
+        @logger.info( 'System' ){ 'RPC Server started.' }
+        @logger.info( 'System' ) do
+            interface = @socket ? @socket : "#{@host}:#{@port}"
+            "Listening on #{interface}"
+        end
+
+        opts = @socket ? @socket : [@host, @port]
+        @reactor.listen( *[opts, Handler, self].flatten )
+    end
+
+    # @note If the called method is asynchronous it will be sent by this method
+    #   directly, otherwise it will be handled by the {Handler}.
+    #
+    # @param    [Handler]   connection
+    #   Connection with request information.
+    #
+    # @return   [Response]
+    def call( connection )
+        req          = connection.request
+        peer_ip_addr = connection.peer_address
+
+        expr, args = req.message, req.args
+        meth_name, obj_name = parse_expr( expr )
+
+        log_call( peer_ip_addr, expr, *args )
+
+        if !object_exist?( obj_name )
+            msg = "Trying to access non-existent object '#{obj_name}'."
+            @logger.error( 'Call' ){ msg + " [on behalf of #{peer_ip_addr}]" }
+            raise Exceptions::InvalidObject.new( msg )
+        end
+
+        if !public_method?( obj_name, meth_name )
+            msg = "Trying to access non-public method '#{meth_name}'."
+            @logger.error( 'Call' ){ msg + " [on behalf of #{peer_ip_addr}]" }
+            raise Exceptions::InvalidMethod.new( msg )
+        end
+
+        # The handler needs to know if this is an async call because if it is
+        # we'll have already send the response and it doesn't need to do
+        # transmit anything.
+        res = Response.new
+        res.async! if async?( obj_name, meth_name )
+
+        if res.async?
+            @objects[obj_name].send( meth_name.to_sym, *args ) do |obj|
+                res.obj = obj
+                connection.send_response( res )
+            end
+        else
+            res.obj = @objects[obj_name].send( meth_name.to_sym, *args )
+        end
+
+        res
+    end
+
+    # @return   [TrueClass]
+    def alive?
+        true
+    end
+
+    # Shuts down the server after 2 seconds
+    def shutdown
+        wait_for = 2
+
+        @logger.info( 'System' ){ "Shutting down in #{wait_for} seconds..." }
+
+        # Don't die before returning...
+        @reactor.delay( wait_for ) do
+            @reactor.stop
+        end
+        true
+    end
+
+    private
+
+    def async?( objname, method )
+        @async_methods[objname].include?( method )
+    end
+
+    def async_check( method )
+        @async_checks.each { |check| return true if check.call( method ) }
+        false
+    end
+
+    def log_call( peer_ip_addr, expr, *args )
+        msg = "#{expr}"
+
+        # this should be in a @logger.debug call but it'll get out of sync
+        if @logger.level == Logger::DEBUG
+            cargs = args.map { |arg| arg.inspect }
+            msg += "( #{cargs.join( ', ' )} )"
+        end
+
+        msg += " [#{peer_ip_addr}]"
+
+        @logger.info( 'Call' ){ msg }
+    end
+
+    def parse_expr( expr )
+        parts = expr.to_s.split( '.' )
+        # method name, object name
+        [ parts.pop, parts.join( '.' ) ]
+    end
+
+    def object_exist?( obj_name )
+        @objects[obj_name] ? true : false
+    end
+
+    def public_method?( obj_name, method )
+        @methods[obj_name].include?( method )
+    end
+
+end
+
+end
+end