arachni-rpc-em 0.1

data/examples/client.EM.run.rb

@@ -0,0 +1,113 @@
+=begin
+                  Arachni-RPC
+  Copyright (c) 2011 Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+
+  This is free software; you can copy and distribute and modify
+  this program under the term of the GPL v2.0 License
+  (See LICENSE file for details)
+
+=end
+
+# require 'arachni/rpc'
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), '../lib/arachni/rpc/', 'em' )
+
+#
+# You don't *need* to stick the whole thing inside an ::EM.run block,
+# the system will manage EM on its own...however you *can* if you want to
+# or if you're working inside a framework that already runs EventMachine.
+::EM.run do
+
+    # connect to the server
+    client = Arachni::RPC::EM::Client.new(
+        :host  => 'localhost',
+        :port  => 7332,
+
+        # optional authentication token, if it doesn't match the one
+        # set on the server-side you'll be getting exceptions.
+        :token => 'superdupersecret',
+
+        # :keep_alive => false,
+
+        # optional serializer (defaults to YAML)
+        # see the 'serializer' method at:
+        # http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
+        :serializer => Marshal
+    )
+
+    bench = Arachni::RPC::RemoteObjectMapper.new( client, 'bench' )
+
+    #
+    # There's one downside though, if you want to run this thing inside an
+    # ::EM.run block: you'll have to wrap all sync calls in a ::Arachni::RPC::EM::EM::Synchrony.run block.
+    #
+    # Like so:
+    ::Arachni::RPC::EM::Synchrony.run do
+        p bench.foo( 'First sync call in individual Synchrony block.' )
+        # => "First sync call in individual Synchrony block."
+    end
+
+    # you can use it again individually
+    ::Arachni::RPC::EM::Synchrony.run do
+        p bench.foo( 'Second sync call in individual Synchrony block.' )
+        # => "Second sync call in individual Synchrony block."
+    end
+
+    # or just wrap lots of calls in it
+    ::Arachni::RPC::EM::Synchrony.run do
+        p bench.foo( 'Third sync call in individual Synchrony block.' )
+        # => "Third sync call in individual Synchrony block."
+
+        p bench.foo( '--> And this one is in the same block as well.' )
+        # => "--> And this one is in the same block as well."
+
+        p bench.async_foo( 'This is a sync call to an async remote method.' )
+        # => "This is a sync call to an async remote method."
+    end
+
+    # async calls are the same
+    bench.foo( 'This is an async call... business as usual. :)' ) {
+        |res|
+        p res
+        # => "This is an async call... business as usual. :)"
+    }
+
+    bench.async_foo( 'This is an async call to an async remote method.' ) {
+        |res|
+        p res
+        # => "This is an async call to an async remote method."
+    }
+
+
+    #
+    # The system uses 2 methods to make calls appear sync:
+    #   - Threads (when the code is *not* run directly inside the Reactor's thread, see example.rb)
+    #   - Fibers (when the code *is* run inside the Reactor's thread, like right here)
+    #
+    # For performance reasons callbacks are ::EM.defer'ed.
+    #
+    # This means that they're already in their own thread so you don't need
+    # ::Arachni::RPC::EM::EM::Synchrony.run to perform sync calls from inside callbacks.
+    #
+    bench.async_foo( 'Coo-coo' ) {
+        |res|
+
+        p res
+        # => "Coo-coo"
+
+        p bench.async_foo( 'Coo-coo 2' )
+        # => "Coo-coo 2"
+
+        bench.async_foo( 'Coo-coo 3' ) {
+            |res|
+
+            p res
+            # => "Coo-coo 3"
+
+            p bench.foo( 'Coo-coo 4' )
+            # => "Coo-coo 4"
+        }
+
+    }
+
+
+end

data/examples/client.rb

@@ -0,0 +1,181 @@
+=begin
+                  Arachni-RPC
+  Copyright (c) 2011 Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+
+  This is free software; you can copy and distribute and modify
+  this program under the term of the GPL v2.0 License
+  (See LICENSE file for details)
+
+=end
+
+cwd = File.expand_path( File.dirname( __FILE__ ) )
+require File.join( cwd, '../lib/arachni/rpc/', 'em' )
+
+
+# connect to the server
+client = Arachni::RPC::EM::Client.new(
+    :host  => 'localhost',
+    :port  => 7332,
+
+    # 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)
+    # see the 'serializer' method at:
+    # http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
+    :serializer => Marshal,
+
+    #
+    # Connection keep alive is set to true by default, this means that
+    # a single connection will be maintained and all calls will pass
+    # through it.
+    # This bypasses a bug in EventMachine and allows you to perform thousands
+    # of calls without issue.
+    #
+    # However, you are responsible for closing the connection when you're done.
+    #
+    # If keep alive is set to false then each call will go through its own connection
+    # and the responsibility for closing that connection falls on Arachni-RPC.
+    #
+    # Unfortunately, if you try to make a greater number of calls than your system's
+    # maximum open file descriptors limit EventMachine will freak-out.
+    #
+    :keep_alive => false,
+
+    #
+    # 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'
+)
+
+# Make things easy on the eyes using the mapper, it allows you to do this:
+#
+#    res = bench.foo( arg )
+#
+# Instead of:
+#
+#    res = client.call( 'bench.foo', arg )
+#
+bench = Arachni::RPC::RemoteObjectMapper.new( client, 'bench' )
+
+#
+# In order to perform an asynchronous call you will need to provide a block,
+# even if it is an empty one.
+#
+bench.foo( 'This is an async call to "bench.foo".' ) {
+    |res|
+
+    p res
+    # => "This is an async call to \"bench.foo\"."
+
+    # did something RPC related go wrong?
+    # p res.rpc_exception?
+    # => false
+
+    # did something go wrong on the server-side?
+    # p res.rpc_remote_exception?
+    # => false
+
+    # did the connection die abruptly?
+    # p res.rpc_connection_error?
+    # => false
+
+    # did we call an object for which there is no handler on the server-side?
+    # p res.rpc_invalid_object_error?
+    # => false
+
+    # did we call a server-side method that isn't existent or public?
+    # p res.rpc_invalid_method_error?
+    # => false
+
+    # was there an authentication token mismatch?
+    # p res.rpc_invalid_token_error?
+    # => false
+}
+
+
+
+#
+# On the server-side this is an async method but works just like everything else here.
+#
+# You'll need to kind-of specify the async methods on the server-side,
+# check the server example file for more info.
+#
+bench.async_foo( 'This is an async call to "bench.async_foo".' ) {
+    |res|
+    p res
+    # => "This is an async call to \"bench.async_foo\"."
+}
+
+p bench.async_foo( 'This is a sync call to "bench.async_foo".' )
+# => "This is a sync call to \"bench.async_foo\"."
+
+
+#
+# To perform a sync (blocking) call do the usual stuff.
+#
+# This is thread safe so if you'd rather use Threads instead of async calls
+# for that extra performance kick you go ahead and do your thing now...
+#
+p bench.foo( 'This is a sync call to "bench.foo".' )
+# => "This is a sync call to \"bench.foo\"."
+
+
+#
+# When you are performing a synchronous call and things go wrong
+# an exception will be thrown.
+#
+# Exceptions on the server-side unrelated to the RPC system will be forwarded.
+#
+
+#
+# Non-existent object.
+#
+blah = Arachni::RPC::RemoteObjectMapper.new( client, 'blah' )
+begin
+    p blah.something
+rescue Exception => e
+    p e  # => #<Arachni::RPC::EM::Exceptions::InvalidObject: Trying to access non-existent object 'blah'.>
+end
+
+#
+# Non-existent or non-public method.
+#
+begin
+    p bench.fdoo
+rescue Exception => e
+    p e # => #<Arachni::RPC::EM::Exceptions::InvalidMethod: Trying to access non-public method 'fdoo'.>
+end
+
+#
+# When you are performing an asynchronous call and things go wrong
+# an exception will be returned.
+#
+# It will *NOT* be thrown!
+# It will be *RETURNED*!
+#
+blah.something {
+    |res|
+    p res # => #<Arachni::RPC::EM::Exceptions::InvalidObject: Trying to access non-existent object 'blah'.>
+
+    # RPC Exception helper methods have been added to all Ruby objects (except BasicObject)
+    # so they'll always be there when you need them.
+
+    # p res.rpc_exception? # => true
+    # p res.rpc_invalid_object_error? # => true
+}
+
+#
+# We don't know when async calls will return so we wait forever.
+#
+# Call ::EM.stop to break-out.
+#
+Arachni::RPC::EM.block!
+

data/examples/server.rb

@@ -0,0 +1,80 @@
+=begin
+                  Arachni-RPC
+  Copyright (c) 2011 Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+
+  This is free software; you can copy and distribute and modify
+  this program under the term of the GPL v2.0 License
+  (See LICENSE file for details)
+
+=end
+
+cwd = File.expand_path( File.dirname( __FILE__ ) )
+require File.join( cwd, '../lib/arachni/rpc/', 'em' )
+
+class Parent
+    def foo( arg )
+        return arg
+    end
+end
+
+class Bench < Parent
+
+    # in order to make inherited methods accessible you've got to explicitly
+    # make them public
+    private :foo
+    public :foo
+
+    #
+    # Uses EventMachine to call the block asynchronously
+    #
+    def async_foo( arg, &block )
+        ::EM.schedule {
+            ::EM.defer {
+                block.call( arg ) if block_given?
+            }
+        }
+    end
+
+end
+
+server = Arachni::RPC::EM::Server.new(
+    :host  => 'localhost',
+    :port  => 7332,
+
+    # optional authentication token, if it doesn't match the one
+    # set on the client-side the client won't be able to do anything
+    # and keep getting exceptions.
+    :token => 'superdupersecret',
+
+    # optional serializer (defaults to YAML)
+    # see the 'serializer' method at:
+    # http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
+    :serializer => Marshal,
+
+    # :ssl_ca     => cwd + '/../spec/pems/cacert.pem',
+    # :ssl_pkey   => cwd + '/../spec/pems/server/key.pem',
+    # :ssl_cert   => cwd + '/../spec/pems/server/cert.pem'
+)
+
+#
+# This is a way for you 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 convetions to fit the RPC stuff,
+# you can just decide dynamically based on a plethora of data which Ruby provides
+# by its 'Method' class.
+#
+server.add_async_check {
+    |method|
+    #
+    # Must return 'true' for async and 'false' for sync.
+    #
+    # Very simple check here...
+    #
+    'async' ==  method.name.to_s.split( '_' )[0]
+}
+
+server.add_handler( 'bench', Bench.new )
+
+# this will block forever, call server.shutdown to kill the server.
+server.run

data/lib/arachni/rpc/em.rb

@@ -0,0 +1,26 @@
+=begin
+                  Arachni
+  Copyright (c) 2010-2011 Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+
+  This is free software; you can copy and distribute and modify
+  this program under the term of the GPL v2.0 License
+  (See LICENSE file for details)
+
+=end
+
+require 'eventmachine'
+require 'socket'
+require 'logger'
+require 'fiber'
+
+require 'arachni/rpc'
+
+require 'yaml'
+YAML::ENGINE.yamler = 'syck'
+
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'connection_utilities' )
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'ssl' )
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'protocol' )
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'server' )
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'client' )
+require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'em', 'em' )

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

@@ -0,0 +1,280 @@
+=begin
+                  Arachni-RPC
+  Copyright (c) 2011 Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+
+  This is free software; you can copy and distribute and modify
+  this program under the term of the GPL v2.0 License
+  (See LICENSE file for details)
+
+=end
+
+module Arachni
+module RPC
+module EM
+
+#
+# Simple EventMachine-based RPC client.
+#
+# 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 remote asynchronous calls that require a block
+#
+# @author: Tasos "Zapotek" Laskos
+#                                      <tasos.laskos@gmail.com>
+#                                      <zapotek@segfault.gr>
+# @version: 0.1
+#
+class Client
+
+    include ::Arachni::RPC::Exceptions
+
+    #
+    # Handles EventMachine's connection and RPC related stuff.
+    #
+    # It's responsible for TLS, storing and calling callbacks as well as
+    # serializing, transmitting and receiving objects.
+    #
+    # @author: Tasos "Zapotek" Laskos
+    #                                      <tasos.laskos@gmail.com>
+    #                                      <zapotek@segfault.gr>
+    # @version: 0.1
+    #
+    class Handler < EventMachine::Connection
+        include ::Arachni::RPC::EM::Protocol
+        include ::Arachni::RPC::EM::ConnectionUtilities
+
+        def initialize( opts )
+            @opts = opts
+            @status = :idle
+
+            @request = nil
+            assume_client_role!
+        end
+
+        def post_init
+            @status = :active
+            start_ssl
+        end
+
+        def unbind( reason )
+            end_ssl
+
+            if @request && @request.callback && @status != :done
+                e = Arachni::RPC::Exceptions::ConnectionError.new( "Connection closed [#{reason}]" )
+                @request.callback.call( e )
+            end
+
+            @status = :closed
+        end
+
+        def connection_completed
+            @status = :established
+        end
+
+        def status
+            @status
+        end
+
+        #
+        # Used to handle responses.
+        #
+        # @param    [Arachni::RPC::EM::Response]    res
+        #
+        def receive_response( res )
+
+            if exception?( res )
+                res.obj = Arachni::RPC::Exceptions.from_response( res )
+            end
+
+            if cb = @request.callback
+
+                callback = Proc.new {
+                    |obj|
+                    cb.call( obj )
+
+                    @status = :done
+                    close_connection
+                }
+
+                if @request.defer?
+                    # the callback might block a bit so tell EM to put it in a thread
+                    ::EM.defer {
+                        callback.call( res.obj )
+                    }
+                else
+                    callback.call( res.obj )
+                end
+            end
+        end
+
+        # @param    [Arachni::RPC::EM::Response]    res
+        def exception?( res )
+            res.obj.is_a?( Hash ) && res.obj['exception'] ? true : false
+        end
+
+        #
+        # Sends the request.
+        #
+        # @param    [Arachni::RPC::EM::Request]      req
+        #
+        def send_request( req )
+            @status = :pending
+            @request = req
+            super( req )
+        end
+    end
+
+    #
+    # Options hash
+    #
+    # @return   [Hash]
+    #
+    attr_reader :opts
+
+    #
+    # Starts EventMachine and connects to the remote server.
+    #
+    # opts example:
+    #
+    #    {
+    #        :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)
+    #        # see the 'serializer' method at:
+    #        # http://eventmachine.rubyforge.org/EventMachine/Protocols/ObjectProtocol.html#M000369
+    #        :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
+    #
+    def initialize( opts )
+
+        begin
+            @opts  = opts.merge( :role => :client )
+            @token = @opts[:token]
+
+            @host, @port = @opts[:host], @opts[:port]
+
+            Arachni::RPC::EM.ensure_em_running!
+        rescue EventMachine::ConnectionError => e
+            exc = ConnectionError.new( e.to_s + " for '#{@k}'." )
+            exc.set_backtrace( e.backtrace )
+            raise exc
+        end
+    end
+
+    #
+    # Calls a remote method and grabs the result.
+    #
+    # There are 2 ways to perform a call, async (non-blocking) and sync (blocking).
+    #
+    # To perform an async call you need to provide a block which will be passed
+    # the return value once the method has finished executing.
+    #
+    #    server.call( 'handler.method', arg1, arg2 ){
+    #        |res|
+    #        do_stuff( res )
+    #    }
+    #
+    #
+    # To perform a sync (blocking) call do not pass a block, the value will be
+    # returned as usual.
+    #
+    #    res = server.call( 'handler.method', arg1, arg2 )
+    #
+    # @param    [String]    msg     in the form of <i>handler.method</i>
+    # @param    [Array]     args    collection of argumenta to be passed to the method
+    # @param    [Proc]      &block
+    #
+    def call( msg, *args, &block )
+
+        req = Request.new(
+            :message  => msg,
+            :args     => args,
+            :callback => block,
+            :token    => @token
+        )
+
+        if block_given?
+            call_async( req )
+        else
+            return call_sync( req )
+        end
+    end
+
+    private
+
+    def connect
+        ::EM.connect( @host, @port, Handler, @opts )
+    end
+
+    def call_async( req, &block )
+        ::EM.schedule {
+            req.callback = block if block_given?
+            connect.send_request( req )
+        }
+    end
+
+    def call_sync( req )
+
+        ret = nil
+        # if we're in the Reactor thread use a Fiber and if we're not
+        # use a Thread
+        if !::EM::reactor_thread?
+            t = Thread.current
+            call_async( req ) {
+                |obj|
+                t.wakeup
+                ret = obj
+            }
+            sleep
+        else
+            # Fibers do not work across threads so don't defer the callback
+            # once the Handler gets to it
+            req.do_not_defer!
+
+            f = Fiber.current
+            call_async( req ) {
+                |obj|
+                f.resume( obj )
+            }
+
+            begin
+                ret = Fiber.yield
+            rescue FiberError => e
+                msg = e.to_s + "\n"
+                msg += '(Consider wrapping your sync code in a' +
+                    ' "::Arachni::RPC::EM::Synchrony.run" ' +
+                    'block when your app is running inside the Reactor\'s thread)'
+
+                raise( msg )
+            end
+        end
+
+        raise ret if ret.is_a?( Exception )
+        return ret
+    end
+
+end
+
+end
+end
+end