toq 0.0.1

data/lib/toq/exceptions.rb

@@ -0,0 +1,152 @@
+=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
+
+# RPC Exceptions have methods that help identify them based on type.
+#
+# So in order to allow evaluations like:
+#
+#    my_object.rpc_connection_error?
+#
+# to be possible on all objects these helper methods need to be available for
+# all objects.
+#
+# By default they'll return false, individual RPC Exceptions will overwrite them
+# to return true when applicable.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Object
+
+    # @return   [Bool]  false
+    def rpc_connection_error?
+        false
+    end
+
+    # @return   [Bool]  false
+    def rpc_remote_exception?
+        false
+    end
+
+    # @return   [Bool]  false
+    def rpc_invalid_object_error?
+        false
+    end
+
+    # @return   [Bool]  false
+    def rpc_invalid_method_error?
+        false
+    end
+
+    # @return   [Bool]  false
+    def rpc_invalid_token_error?
+        false
+    end
+
+    # @return   [Bool]  true
+    def rpc_ssl_error?
+        false
+    end
+
+    # @return   [Bool]  false
+    def rpc_exception?
+        false
+    end
+
+end
+
+module Toq
+module Exceptions
+
+    # Returns an exception based on the response object.
+    #
+    # @param    [Toq::Response]    response
+    #
+    # @return   [Exception]
+    def self.from_response( response )
+        exception = response.exception
+        klass = Toq::Exceptions.const_get( exception['type'].to_sym )
+        e = klass.new( exception['message'] )
+        e.set_backtrace( exception['backtrace'] )
+        e
+    end
+
+    class Base < ::RuntimeError
+
+        # @return   [Bool]  true
+        def rpc_exception?
+            true
+        end
+    end
+
+    # Signifies an abruptly terminated connection.
+    #
+    # Look for network or SSL errors or a dead server or a mistyped server address/port.
+    class ConnectionError < Base
+
+        # @return   [Bool]  true
+        def rpc_connection_error?
+            true
+        end
+    end
+
+    # Signifies an exception that occurred on the server-side.
+    #
+    # Look errors on the remote method and review the server output for more details.
+    class RemoteException < Base
+
+        # @return   [Bool]  true
+        def rpc_remote_exception?
+            true
+        end
+    end
+
+    # An invalid object has been called.
+    #
+    # Make sure that there is a server-side handler for the object you called.
+    class InvalidObject < Base
+
+        # @return   [Bool]  true
+        def rpc_invalid_object_error?
+            true
+        end
+
+    end
+
+    # An invalid method has been called.
+    #
+    # Occurs when a remote method doesn't exist or isn't public.
+    class InvalidMethod < Base
+
+        # @return   [Bool]  true
+        def rpc_invalid_method_error?
+            true
+        end
+
+    end
+
+    # Signifies an authentication token mismatch between the client and the server.
+    class InvalidToken  < Base
+
+        # @return   [Bool]  true
+        def rpc_invalid_token_error?
+            true
+        end
+
+    end
+
+    # Signifies an authentication token mismatch between the client and the server.
+    class SSLPeerVerificationFailed < ConnectionError
+
+        # @return   [Bool]  true
+        def rpc_ssl_error?
+            true
+        end
+
+    end
+
+end
+end

data/lib/toq/message.rb

@@ -0,0 +1,63 @@
+=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 Toq
+
+# Represents an RPC message, serves as the basis for {Request} and {Response}.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Message
+
+    # @param    [Hash]   opts
+    #   Sets instance attributes.
+    def initialize( opts = {} )
+        opts.each_pair { |k, v| send( "#{k}=".to_sym, v ) }
+    end
+
+    # Merges the attributes of another message with self.
+    #
+    # (The param doesn't *really* have to be a message, any object will do.)
+    #
+    # @param    [Message]   message
+    def merge!( message )
+        message.instance_variables.each do |var|
+            val = message.instance_variable_get( var )
+            instance_variable_set( var, val )
+        end
+    end
+
+    # Prepares the message for transmission (i.e. converts the message to a `Hash`).
+    #
+    # Attributes that should not be included can be skipped by implementing
+    # {#transmit?} and returning the appropriate value.
+    #
+    # @return   [Hash]
+    def prepare_for_tx
+        instance_variables.inject({}) do |h, k|
+            h[normalize( k )] = instance_variable_get( k ) if transmit?( k )
+            h
+        end
+    end
+
+    # Decides which attributes should be skipped by {#prepare_for_tx}.
+    #
+    # @param    [Symbol]    attr
+    #   Instance variable symbol (i.e. `:@token`).
+    def transmit?( attr )
+        true
+    end
+
+    private
+
+    def normalize( attr )
+        attr.to_s.gsub( '@', '' )
+    end
+
+end
+
+end

data/lib/toq/protocol.rb

@@ -0,0 +1,101 @@
+=begin
+
+    This file is part of the Arachni-RPC 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 Toq
+
+# Provides helper transport methods for {Message} transmission.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+module Protocol
+    include Raktr::Connection::TLS
+
+    # Initializes an SSL session once the connection has been established and
+    # sets {#status} to `:ready`.
+    #
+    # @private
+    def on_connect
+        start_tls(
+            ca:          @opts[:ssl_ca],
+            private_key: @opts[:ssl_pkey],
+            certificate: @opts[:ssl_cert]
+        )
+
+        @status = :ready
+    end
+
+    # @param    [Message]    msg
+    #   Message to send to the peer.
+    def send_message( msg )
+        send_object( msg.prepare_for_tx )
+    end
+    alias :send_request  :send_message
+    alias :send_response :send_message
+
+    # Receives data from the network.
+    #
+    # Rhe data will be chunks of a serialized object which will be buffered
+    # until the whole transmission has finished.
+    #
+    # It will then unserialize it and pass it to {#receive_object}.
+    def on_read( data )
+        (@buf ||= '') << data
+
+        while @buf.size >= 4
+            if @buf.size >= 4 + ( size = @buf.unpack( 'N' ).first )
+                @buf.slice!( 0, 4 )
+                receive_object( unserialize( @buf.slice!( 0, size ) ) )
+            else
+                break
+            end
+        end
+    end
+
+    private
+
+    # Stub method, should be implemented by servers.
+    #
+    # @param    [Request]     request
+    # @abstract
+    def receive_request( request )
+        p request
+    end
+
+    # Stub method, should be implemented by clients.
+    #
+    # @param    [Response]    response
+    # @abstract
+    def receive_response( response )
+        p response
+    end
+
+    #   Object to send.
+    def send_object( obj )
+        data = serialize( obj )
+        write [data.bytesize, data].pack( 'Na*' )
+    end
+
+    # Returns the preferred serializer based on the `serializer` option of the
+    # server.
+    #
+    # @return   [.load, .dump]
+    #   Serializer to be used (Defaults to `YAML`).
+    def serializer
+        @opts[:serializer] || YAML
+    end
+
+    def serialize( obj )
+        serializer.dump obj
+    end
+
+    def unserialize( obj )
+        serializer.load( obj )
+    end
+
+end
+
+end

data/lib/toq/proxy.rb

@@ -0,0 +1,84 @@
+=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 Toq
+
+# Maps the methods of remote objects to local ones.
+#
+# You start like:
+#
+#     client = Toq::Client.new( host: 'localhost', port: 7331 )
+#     bench  = Toq::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 = Toq::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

data/lib/toq/request.rb

@@ -0,0 +1,59 @@
+=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
+
+require_relative 'message'
+
+module Toq
+
+# 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:
+#
+#
+#     {
+#         # 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
+#     }
+#
+# 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
+
+    # @return   [String]
+    #   RPC message in the form of 'handler.method'.
+    attr_accessor :message
+
+    # @return   [Array]
+    #   Optional arguments for the remote method.
+    attr_accessor :args
+
+    # @return   [String]
+    #   Optional authentication token.
+    attr_accessor :token
+
+    # @return   [Proc]
+    #   Callback to be invoked on the response.
+    attr_accessor :callback
+
+    private
+
+    def transmit?( attr )
+        ![ :@callback ].include?( attr )
+    end
+
+end
+
+end

data/lib/toq/response.rb

@@ -0,0 +1,63 @@
+=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 Toq
+
+# 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:
+#
+#    {
+#        # result of the RPC call
+#        'obj' => object
+#    }
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Response < Message
+
+    # @return   [Object]
+    #   Return object of the {Request#message}.
+    attr_accessor :obj
+
+    # @return   [Hash]
+    #
+    #       {
+    #           "name" => "Trying to access non-existent object 'blah'.",
+    #           "backtrace" => [
+    #               [0] "/home/zapotek/workspace/arachni-rpc/lib/toq/server.rb:285:in `call'",
+    #               [1] "/home/zapotek/workspace/arachni-rpc/lib/toq/server.rb:85:in `block in receive_object'",
+    #           ],
+    #           "type" => "InvalidObject"
+    #       }
+    #
+    #   For all available exception types look at {Exceptions}.
+    attr_accessor :exception
+
+    def exception?
+        !!exception
+    end
+
+    def async?
+        !!@async
+    end
+
+    def async!
+        @async = true
+    end
+
+    private
+
+    def transmit?( attr )
+        ![:@async].include?( attr )
+    end
+
+end
+
+end

data/lib/toq/server/handler.rb

@@ -0,0 +1,144 @@
+=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 Toq
+class Server
+
+# Receives {Request} objects and transmits {Response} objects.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Handler < Raktr::Connection
+    include Raktr::Connection::PeerInfo
+    include Toq::Protocol
+
+    # @return   [Request]
+    #   Working RPC request.
+    attr_reader :request
+
+    # @param    [Server]    server
+    #   RPC server.
+    def initialize( server )
+        @server  = server
+        @opts    = server.opts.dup
+        @request = nil
+    end
+
+    # Handles closed connections and cleans up the SSL session.
+    #
+    # @private
+    def on_close( _ )
+        @server = nil
+    end
+
+    # * Handles {Request}
+    # * Sets the {#request}.
+    # * Sends back {Response}.
+    #
+    # @param    [Request]     req
+    def receive_request( req )
+        @request = req
+
+        # Create an empty response to be filled in little by little.
+        res  = Response.new
+        peer = peer_ip_address
+
+        begin
+            # Make sure the client is allowed to make RPC calls.
+            authenticate!
+
+            # Grab the partially filled in response which includes the result
+            # of the RPC call and merge it with out prepared response.
+            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 RemoteException.
+            else
+                type = 'RemoteException'
+            end
+
+            # RPC conventions for exception transmission.
+            res.exception = {
+                'type'      => type,
+                'message'   => e.to_s,
+                'backtrace' => e.backtrace
+            }
+
+            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 but *only* if it
+        # wasn't async, otherwise {Server#call} will have already taken care of it.
+        send_response( res ) if !res.async?
+    end
+
+    private
+
+    # Converts incoming hash objects to {Request} objects and calls
+    # {#receive_request}.
+    #
+    # @param    [Hash]      obj
+    def receive_object( obj )
+        receive_request( Request.new( obj ) )
+    end
+
+    # @param    [Symbol]    severity
+    #
+    #   Severity of the logged event:
+    #
+    #   * `:debug`
+    #   * `:info`
+    #   * `:warn`
+    #   * `:error`
+    #   * `:fatal`
+    #   * `:unknown`
+    #
+    # @param    [String]    category
+    #   Category of message (SSL, Call, etc.).
+    # @param    [String]    msg
+    #   Message to log.
+    def log( severity, category, msg )
+        sev_sym = Logger.const_get( severity.to_s.upcase.to_sym )
+        @server.logger.add( sev_sym, msg, category )
+    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!
+        return if valid_token?( @request.token )
+
+        msg = "Token missing or invalid while calling: #{@request.message}"
+
+        @server.logger.error( 'Authenticator' ){
+            msg + " [on behalf of #{peer_ip_address}]"
+        }
+
+        fail Exceptions::InvalidToken.new( msg )
+    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
+end
+end