arachni-rpc-em 0.1.3 → 0.2

data/lib/arachni/rpc/em/client/handler.rb

@@ -0,0 +1,180 @@
+=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
+
+module Arachni
+module RPC::EM
+class Client
+
+#
+# Transmits `Arachni::RPC::Request` objects and calls callbacks once an
+# `Arachni::RPC::Response` is received.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+#
+class Handler < EventMachine::Connection
+    include Protocol
+    include ConnectionUtilities
+
+    # Default amount of tries for failed requests.
+    DEFAULT_TRIES = 9
+
+    # @return   [Symbol]    Status of the connection, can be:
+    #
+    # * `:idle` -- Just initialized.
+    # * `:ready` -- A connection has been established.
+    # * `:pending` -- Sending request and awaiting response.
+    # * `:done` -- Response received and callback invoked -- ready to be reused.
+    # * `:closed` -- Connection closed.
+    attr_reader :status
+
+    # Prepares an RPC connection and sets {#status} to `:idle`.
+    #
+    # @param    [Hash]  opts
+    # @option   opts    [Integer]   :max_retries    (9)
+    #   Default amount of tries for failed requests.
+    #
+    # @option   opts    [Client]   :base
+    #   Client instance (needed to {Client#push_connection push} ourselves
+    #   back to its connection pool once we're done and we're ready to be reused.)
+    def initialize( opts )
+        @opts = opts.dup
+
+        @max_retries = @opts[:max_retries] || DEFAULT_TRIES
+
+        @client = @opts[:client]
+
+        @opts[:tries] ||= 0
+        @tries ||= @opts[:tries]
+
+        @status = :idle
+
+        @request = nil
+        assume_client_role!
+    end
+
+    # Sends an RPC request (i.e. performs an RPC call) and sets {#status}
+    # to `:pending`.
+    #
+    # @param    [Arachni::RPC::Request]      req
+    def send_request( req )
+        @request = req
+        @status  = :pending
+        super( req )
+    end
+
+    # @note Pushes itself to the client's connection pool to be re-used.
+    #
+    # Handles responses to RPC requests, calls its callback and sets {#status}
+    # to `:done`.
+    #
+    # @param    [Arachni::RPC::Response]    res
+    #
+    def receive_response( res )
+        if exception?( res )
+            res.obj = RPC::Exceptions.from_response( res )
+        end
+
+        @request.callback.call( res.obj ) if @request.callback
+    ensure
+        @request = nil # Help the GC out.
+        @status  = :done
+        @opts[:tries] = @tries = 0
+        @client.push_connection self
+    end
+
+    # Initializes an SSL session once the connection has been established and
+    # sets {#status} # to `:ready`.
+    #
+    # @private
+    def post_init
+        @status = :ready
+        start_ssl
+    end
+
+    # Handles closed connections, cleans up the SSL session, retries (if
+    # necessary) and sets {#status} to `:closed`.
+    #
+    # @private
+    def unbind( reason )
+        end_ssl
+
+        # If there is a request and a callback and the callback hasn't yet be
+        # called (i.e. not done) then we got here by error so retry.
+        if @request && @request.callback && !done?
+            if retry? #&& reason == Errno::ECONNREFUSED
+                #p 'RETRY'
+                #p @client.connection_count
+                retry_request
+            else
+                #p 'FAIL'
+                #p @client.connection_count
+                e = RPC::Exceptions::ConnectionError.new( "Connection closed [#{reason}]" )
+                @request.callback.call( e )
+                @client.connection_failed self
+            end
+            return
+        end
+
+        close_without_retry
+    end
+
+    # @return   [Boolean]
+    #   `true` when the connection has been closed, `false` otherwise.
+    def closed?
+        @status == :closed
+    end
+
+    # @note If `true`, the connection can be re-used.
+    #
+    # @return   [Boolean]
+    #   `true` when the connection is done, `false` otherwise.
+    def done?
+        @status == :done
+    end
+
+    # Closes the connection without triggering a retry operation and sets
+    # {#status} to `:closed`.
+    def close_without_retry
+        @request = nil
+        @status  = :closed
+        close_connection
+    end
+
+    private
+
+    def retry_request
+        opts = @opts.dup
+        opts[:tries] += 1
+
+        req = @request.dup
+
+        @tries += 1
+        ::EM.next_tick {
+            ::EM::Timer.new( 0.2 ) {
+                address = opts[:socket] ? opts[:socket] : [opts[:host], opts[:port]]
+                ::EM.connect( *[address, self.class, opts ].flatten ).send_request( req )
+            }
+        }
+
+        close_without_retry
+    end
+
+    def retry?
+        @tries < @max_retries
+    end
+
+    # @param    [Arachni::RPC::Response]    res
+    def exception?( res )
+        res.obj.is_a?( Hash ) && res.obj['exception'] ? true : false
+    end
+
+end
+
+end
+end
+end

data/lib/arachni/rpc/em/connection_utilities.rb

@@ -13,13 +13,11 @@ module EM
 #
 # Helper methods to be included in EventMachine::Connection classes
 #
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
 #
 module ConnectionUtilities
 
-    #
     # @return   [String]    IP address of the client
-    #
     def peer_ip_addr
         begin
             if peername = get_peername

data/lib/arachni/rpc/em/em.rb

@@ -12,7 +12,7 @@ module RPC
 #
 # Provides some convenient methods for EventMachine's Reactor.
 #
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
 #
 module EM
 
@@ -24,27 +24,21 @@ module EM
         extend self
     end
 
+    # @note Will make sure EM is running first.
     #
-    # Schedules a block to be run in the EM reactor.
-    #
-    # @param    [Proc]    &block
-    #
+    # @param    [Block]    block Block to be run in the EM reactor.
     def schedule( &block )
         ensure_em_running
         ::EM.schedule( &block )
     end
 
-    #
     # Blocks until the Reactor stops running
-    #
     def block
         # beware of deadlocks, we can't join our own thread
         ::EM.reactor_thread.join if ::EM.reactor_thread && !::EM::reactor_thread?
     end
 
-    #
     # Puts the Reactor in its own thread and runs it.
-    #
     def ensure_em_running
         if !::EM::reactor_running?
 

data/lib/arachni/rpc/em/protocol.rb

@@ -11,64 +11,18 @@ module RPC
 module EM
 
 #
-# Provides helper transport methods for {Message} transmission.
+# Provides helper transport methods for `Arachni::RPC::Message` transmission.
 #
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
 #
 module Protocol
     include ::Arachni::RPC::EM::SSL
 
-    # send a maximum of 16kb of data per tick
+    # Send a maximum of 16kb of data per tick.
     MAX_CHUNK_SIZE = 1024 * 16
 
-    # become a server
-    def assume_server_role!
-        @role = :server
-    end
-
-    # become a client
-    def assume_client_role!
-        @role = :client
-    end
-
-    #
-    # Stub method, should be implemented by servers.
-    #
-    # @param    [Arachni::RPC::EM::Request]     request
-    #
-    def receive_request( request )
-        p request
-    end
-
-    #
-    # Stub method, should be implemented by clients.
-    #
-    # @param    [Arachni::RPC::EM::Response]    response
-    #
-    def receive_response( response )
-        p response
-    end
-
-    #
-    # Converts incoming hash objects to Requests or Response
-    # (depending on the assumed role) and calls receive_request() or receive_response()
-    # accordingly.
-    #
-    # @param    [Hash]      obj
-    #
-    def receive_object( obj )
-        if @role == :server
-            receive_request( Request.new( obj ) )
-        else
-            receive_response( Response.new( obj ) )
-        end
-    end
-
-    #
-    # Sends a message to the peer.
-    #
-    # @param    [Arachni::RPC::EM::Message]    msg
-    #
+    # @param    [Arachni::RPC::Message]    msg
+    #   Message to send to the peer.
     def send_message( msg )
         ::EM.schedule { send_object( msg.prepare_for_tx ) }
     end
@@ -78,18 +32,14 @@ module Protocol
     #
     # Receives data from the network.
     #
-    # In this case the data will be chunks of a serialized object which
-    # will be buffered until the whole transmission has finished.
+    # Rhe data will be chunks of a serialized object which will be buffered
+    # until the whole transmission has finished.
     #
-    # It will then unresialize it and pass it to receive_object().
+    # It will then unserialize it and pass it to {#receive_object}.
     #
     def receive_data( data )
-        #
-        # cut them out as soon as possible
-        #
-        # don't buffer any data from unverified peers if SSL peer
-        # verification has been enabled
-        #
+        # Break out early if the request is sent by an unverified peer and SSL
+        # peer verification has been enabled.
         if ssl_opts? && !verified_peer? && @role == :server
             e = Arachni::RPC::Exceptions::SSLPeerVerificationFailed.new( 'Could not verify peer.' )
             send_response Response.new( :obj => {
@@ -114,11 +64,45 @@ module Protocol
         end
     end
 
+    private
+
+    # Stub method, should be implemented by servers.
+    #
+    # @param    [Arachni::RPC::Request]     request
+    # @abstract
+    def receive_request( request )
+        p request
+    end
+
+    #
+    # Stub method, should be implemented by clients.
     #
-    # Sends a ruby object over the network
+    # @param    [Arachni::RPC::Response]    response
+    # @abstract
+    def receive_response( response )
+        p response
+    end
+
+    #
+    # Converts incoming hash objects to `Arachni::RPC::Request` and
+    # `Arachni::RPC::Response` objects (depending on the assumed role) and calls
+    # {#receive_request} or {#receive_response} accordingly.
+    #
+    # @param    [Hash]      obj
+    #
+    def receive_object( obj )
+        if @role == :server
+            receive_request( Request.new( obj ) )
+        else
+            receive_response( Response.new( obj ) )
+        end
+    end
+
     #
-    # Will split the object in chunks of MAX_CHUNK_SIZE and transmit one at a time.
+    # @note Will split the object in chunks of MAX_CHUNK_SIZE and transmit one
+    #   at a time.
     #
+    # @param    [Object]    obj  Object to send.
     def send_object( obj )
         data = serialize( obj )
         packed = [data.bytesize, data].pack( 'Na*' )
@@ -133,15 +117,20 @@ module Protocol
         end
     end
 
+    # Become a server.
+    def assume_server_role!
+        @role = :server
+    end
+
+    # Become a client.
+    def assume_client_role!
+        @role = :client
+    end
+
+    # Returns the preferred serializer based on the `serializer` option of the
+    # server.
     #
-    # Returns the preferred  based on the 'serializer' option of the server.
-    #
-    # Defaults to <i>YAML</i>.
-    #
-    # @return   [Class]     serializer to be used
-    #
-    # @see http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
-    #
+    # @return   [.load, .dump]     Serializer to be used (Defaults to `YAML`).
     def serializer
         return @client_serializer if @client_serializer
 

data/lib/arachni/rpc/em/server.rb

@@ -10,159 +10,27 @@ module Arachni
 module RPC
 module EM
 
+require_relative 'server/handler'
+
+# EventMachine-based RPC server.
 #
-# EventMachine-based RPC server class.
-#
-# It's capable of:
-# - performing and handling a few thousands requests per second (depending on call size, network conditions and the like)
-# - TLS encryption
-# - asynchronous and synchronous requests
-# - handling asynchronous methods that require a block
-#
-# @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
-#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
 class Server
     include ::Arachni::RPC::Exceptions
 
-    #
-    # Handles EventMachine's connection stuff.
-    #
-    # It's responsible for TLS, serializing, transmitting and receiving objects,
-    # as well as authenticating the client using the token.
-    #
-    # It also handles and forwards exceptions.
-    #
-    # @author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
-    #
-    class Proxy < EventMachine::Connection
-        include ::Arachni::RPC::EM::Protocol
-        include ::Arachni::RPC::Exceptions
-        include ::Arachni::RPC::EM::ConnectionUtilities
-
-        INACTIVITY_TIMEOUT = 10
-
-        attr_reader :request
-
-        def initialize( server )
-            super
-            @server = server
-            @opts   = server.opts
-
-            assume_server_role!
-
-            @id = nil
-            @request = nil
-
-            # do not tolerate long periods of
-            # inactivity in order to avoid zombie connections
-            set_comm_inactivity_timeout( INACTIVITY_TIMEOUT )
-        end
-
-        # starts TLS
-        def post_init
-            start_ssl
-        end
-
-        def unbind
-            end_ssl
-        end
-
-        def log( severity, progname, msg )
-            sev_sym = Logger.const_get( severity.to_s.upcase.to_sym )
-            @server.logger.add( sev_sym, msg, progname )
-        end
-
-        #
-        # Handles requests and sends back the responses.
-        #
-        # @param    [Arachni::RPC::EM::Request]     req
-        #
-        def receive_request( req )
-            @request = req
-
-            # the method call may block a little so tell EventMachine to
-            # stick it in its own thread.
-            res  = Response.new
-            peer = peer_ip_addr
-
-            begin
-                # token-based authentication
-                authenticate!
-
-                # grab the result of the method call
-                res.merge!( @server.call( self ) )
-
-            # handle exceptions and convert them to a simple hash,
-            # ready to be passed to the client.
-            rescue Exception => e
-
-                type = ''
-
-                # if it's an RPC exception pass the type along as is
-                if e.rpc_exception?
-                    type = e.class.name.split( ':' )[-1]
-                # otherwise set it to a RemoteExeption
-                else
-                    type = 'RemoteException'
-                end
-
-                res.obj = {
-                    'exception' => e.to_s,
-                    'backtrace' => e.backtrace,
-                    'type'      => type
-                }
-
-                msg = "#{e.to_s}\n#{e.backtrace.join( "\n" )}"
-                @server.logger.error( 'Exception' ){ msg + " [on behalf of #{peer}]" }
-            end
-
-            #
-            # pass the result of the RPC call back to the client
-            # along with the callback ID but *only* if it wan't async
-            # because server.call() will have already taken care of it
-            #
-            send_response( res ) if !res.async?
-        end
-
-        #
-        # Authenticates the client based on the token in the request.
-        #
-        # It will raise an exception if the token doesn't check-out.
-        #
-        def authenticate!
-            if !valid_token?( @request.token )
-
-                msg = 'Token missing or invalid while calling: ' + @request.message
-
-                @server.logger.error( 'Authenticator' ){
-                    msg + " [on behalf of #{peer_ip_addr}]"
-                }
-
-                fail InvalidToken.new( msg )
-            end
-        end
-
-        #
-        # Compares the authentication token in the param with the one of the server.
-        #
-        # @param    [String]    token
-        #
-        # @return   [Bool]
-        #
-        def valid_token?( token )
-            token == @server.token
-        end
-
-    end
-
+    # @return   [String]    Authentication token.
     attr_reader :token
+
+    # @return   [Hash]  Configuration options.
     attr_reader :opts
+
+    # @return   [Logger]
     attr_reader :logger
 
     #
     # Starts EventMachine and the RPC server.
     #
-    # opts example:
+    # @example  Example options:
     #
     #    {
     #        :host  => 'localhost',
@@ -173,8 +41,6 @@ class Server
     #        :token => 'superdupersecret',
     #
     #        # optional serializer (defaults to YAML)
-    #        # see the 'serializer' method at:
-    #        # http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
     #        :serializer => Marshal,
     #
     #        # serializer to use if the first choice fails
@@ -193,17 +59,30 @@ class Server
     #    }
     #
     # @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
+        @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]
+                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]
+                raise "Could not find certificate at: #{@opts[:ssl_cert]}"
             end
         end
 
@@ -213,17 +92,19 @@ class Server
         @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
 
         clear_handlers
     end
 
     #
-    # This is a way to identify methods that pass their result to a block
-    # instead of simply returning them (which is the most usual operation of async methods.
-    #
-    # So no need to change your coding conventions to fit the RPC stuff,
-    # you can just decide dynamically based on the plethora of data which Ruby provides
-    # by its 'Method' class.
+    # @example
     #
     #    server.add_async_check do |method|
     #        #
@@ -234,35 +115,39 @@ class Server
     #        'async' ==  method.name.to_s.split( '_' )[0]
     #    end
     #
-    # @param    [Proc]  &block
+    # @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
 
     #
-    # Adds a handler by name:
+    # @example
     #
     #    server.add_handler( 'myclass', MyClass.new )
     #
-    # @param    [String]    name    name via which to make the object available over RPC
-    # @param    [Object]    obj     object instance
+    # @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 # no lookup overhead please :)
+        @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
+            @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.
     #
-    # 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 = {}
@@ -271,27 +156,33 @@ class Server
         @async_methods = {}
     end
 
-    #
-    # Runs the server and blocks.
-    #
+    # Runs the server and blocks while EM ir running.
     def run
         Arachni::RPC::EM.schedule { start }
         Arachni::RPC::EM.block
     end
 
-    #
     # Starts the server but does not block.
-    #
     def start
-        @logger.info( 'System' ){ "RPC Server started." }
-        @logger.info( 'System' ){ "Listening on #{@host}:#{@port}" }
+        @logger.info( 'System' ){ 'RPC Server started.' }
+        @logger.info( 'System' ) do
+            interface = @socket ? @socket : "#{@host}:#{@port}"
+            "Listening on #{interface}"
+        end
 
-        ::EM.start_server( @host, @port, Proxy, self )
+        opts = @socket ? @socket : [@host, @port]
+        ::EM.start_server( *[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   [Arachni::RPC::Response]
     def call( connection )
-
-        req = connection.request
+        req          = connection.request
         peer_ip_addr = connection.peer_ip_addr
 
         expr, args = req.message, req.args
@@ -311,40 +202,40 @@ class Server
             raise InvalidMethod.new( msg )
         end
 
-        # the proxy needs to know whether this is an async call because if it
-        # is we'll have already send the response.
+        # 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?
-            res.obj = @objects[obj_name].send( meth_name.to_sym, *args )
-        else
+        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
-        ::EM.add_timer( wait_for ) { ::EM.stop }
+        # Don't die before returning...
+        ::EM.add_timer( wait_for ) do
+            File.unlink( @socket ) if @socket
+            ::EM.stop
+        end
         true
     end
 
@@ -359,7 +250,6 @@ class Server
         false
     end
 
-
     def log_call( peer_ip_addr, expr, *args )
         msg = "#{expr}"