arachni-rpc 0.1.3 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cbbd82c15cfd3db423e6c200ca21a1bfc34ed6d7
+  data.tar.gz: 828f98fbc48632790ff1bb42f723e4e068c924a3
+SHA512:
+  metadata.gz: 75c2287cb0aa85c1cdd66c25068a96db4f180bac1723fde3b46ad451c34afe9a7f45901c6f99b988bc5b4758e6f3fdf763b4f5b8b0ff8395b2cd7abd1c0e6e72
+  data.tar.gz: 1a5fe36d458864aec8f45871e6d650841a47eb0d70ce22f78726eafddaf129ded96c8efd8dbf44dc6ff574b763a57112f1d2e56f895f78d884fb7f326d7daa81

data/CHANGELOG.md

@@ -1,9 +1,15 @@
 # ChangeLog
 
+## Version 0.2.0
+
+- Added `Arachni::Reactor`-based RPC client/server implementation.
+
 ## Version 0.1.3
-- Removed ```Arachni::RPC::Request#do_not_defer``` and ```Arachni::RPC::Request#defer?```.
-- All RPC exceptions now inherit from ```RuntimeError``` instead of ```Exception```.
+
+- Removed `Arachni::RPC::Request#do_not_defer` and `Arachni::RPC::Request#defer?`.
+- All RPC exceptions now inherit from `RuntimeError` instead of `Exception`.
 
 ## Version 0.1.2
+
 - Code cleanup.
-- Arachni::RPC::Request#do_not_defer! => Arachni::RPC::Request#do_not_defer
+- `Arachni::RPC::Request#do_not_defer!` => `Arachni::RPC::Request#do_not_defer`.

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-    Copyright (C) 2011-2012, Tasos Laskos <tasos.laskos@gmail.com>
+    Copyright (C) 2011-2014, Tasos Laskos <tasos.laskos@arachni-scanner.com>
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without modification,

data/README.md

@@ -1,8 +1,9 @@
 # Arachni-RPC
+
 <table>
     <tr>
         <th>Version</th>
-        <td>0.1.2</td>
+        <td>0.2.0</td>
     </tr>
     <tr>
         <th>Github page</th>
@@ -14,7 +15,7 @@
     </tr>
     <tr>
        <th>Author</th>
-       <td><a href="mailto:tasos.laskos@gmail.com">Tasos "Zapotek" Laskos</a></td>
+       <td><a href="mailto:tasos.laskos@arachni-scanner.com">Tasos "Zapotek" Laskos</a></td>
     </tr>
     <tr>
         <th>Twitter</th>
@@ -22,7 +23,7 @@
     </tr>
     <tr>
         <th>Copyright</th>
-        <td>2011-2012</td>
+        <td>2011-2014</td>
     </tr>
     <tr>
         <th>License</th>
@@ -32,56 +33,49 @@
 
 ## Synopsis
 
-Arachni-RPC is a simple and lightweight Remote Procedure Call protocol which provides the basis for <a href="http://arachni.segfault.gr">Arachni</a>'s Grid infrastructure.
-
-This repository holds *only* the protocol specification although there currently are 2 (more like 1.5) available implementations:
+Arachni-RPC is a simple and lightweight Remote Procedure Call protocol and implementation
+which provides the basis for <a href="http://arachni-scanner.com">Arachni</a>'s
+distributed infrastructure.
 
- - <a href="http://github.com/Arachni/arachni-rpc-em">Arachni-RPC EM</a> -- Uses EventMachine for network related operations and provides both a client and a server, this is the one used by Arachni.
- - <a href="http://github.com/Arachni/arachni-rpc-pure">Arachni-RPC Pure</a> -- Provides a synchronous client using pure Ruby OpenSSL sockets and has no 3rd party dependencies.
+(Based on the [Arachni::Reactor](https://github.com/Arachni/arachni-reactor) framework.)
 
 ## Features
 
- - Extremely lightweight
- - Very simple design
- - Token-based authentication
+ - Extremely lightweight.
+ - Very simple design.
+ - TLS encryption.
+ - Configurable serializer.
+    - Can intercept RPC responses and translate them into native objects for
+        when using serializers that only support basic types, like JSON or MessagePack.
+ - Token-based authentication.
+ - Pure-Ruby.
+ - Multi-platform, tested on:
+    - Linux
+    - OSX
+    - Windows
 
 ## Installation
 
-I can't think of a lot of uses for manually installing the protocol specification
-(it'll most likely be installed as a dependency for some other project) but in case you want to some instructions follow.
-
-### Gem
-
-```gem install arachni-rpc```
-
-### Source
-
-If you want to clone the repository and work with the source code:
-
-    git co git://github.com/arachni/arachni-rpc.git
-    cd arachni-rpc
-    rake install
-
+    gem install arachni-rpc
 
 ## Running the Specs
 
-In order to run the specs you must first install RSpec:
-    gem install rspec
-
-Then:
-
+    bundle install
     rake spec
 
 ## Protocol specifications
 
-You can find that information in the [Wiki](https://github.com/Arachni/arachni-rpc/wiki).
+You can find the RPC protocol specification at the
+[Wiki](https://github.com/Arachni/arachni-rpc/wiki).
 
 ## Bug reports/Feature requests
-Please send your feedback using Github's issue system at
+
+Please send your feedback using GitHub's issue system at
 [http://github.com/arachni/arachni-rpc/issues](http://github.com/arachni/arachni-rpc/issues).
 
 
 ## License
-Arachni-RPC is provided under the 3-clause BSD license.<br/>
+
+Arachni-RPC is provided under the 3-clause BSD license.
 See the [LICENSE](file.LICENSE.html) file for more information.
 

data/Rakefile

@@ -19,38 +19,35 @@ end
 
 task default: [ :build, :spec ]
 
-desc "Generate docs"
+desc 'Generate docs'
 task :docs do
-    outdir = "../arachni-rpc-pages"
-    sh "mkdir #{outdir}" if !File.directory?( outdir )
+    outdir = "../arachni-rpc-docs"
+    sh "rm -rf #{outdir}"
+    sh "mkdir -p #{outdir}"
 
-    sh "yardoc --verbose --title \
-      \"Arachni-RPC\" \
-       lib/* -o #{outdir} \
-      - CHANGELOG.md LICENSE.md"
+    sh "yardoc -o #{outdir}"
 
-
-    sh "rm -rf .yard*"
+    sh "rm -rf .yardoc"
 end
 
-desc "Cleaning..."
+desc 'Clean up'
 task :clean do
-    sh "rm *.gem || true"
+    sh 'rm *.gem || true'
 end
 
-desc "Build the arachni-rpc gem."
-task :build => [ :clean ] do
-    sh "gem build arachni-rpc.gemspec"
+desc 'Build the arachni-rpc gem.'
+task build: [ :clean ] do
+    sh 'gem build arachni-rpc.gemspec'
 end
 
-desc "Build and install the arachni gem."
-task :install  => [ :build ] do
+desc 'Build and install the arachni gem.'
+task install: [ :build ] do
     sh "gem install arachni-rpc-#{Arachni::RPC::VERSION}.gem"
 end
 
-desc "Push a new version to Rubygems"
-task :publish => [ :build ] do
+desc 'Push a new version to Rubygems'
+task publish: [ :build ] do
     sh "git tag -a v#{Arachni::RPC::VERSION} -m 'Version #{Arachni::RPC::VERSION}'"
     sh "gem push arachni-rpc-#{Arachni::RPC::VERSION}.gem"
 end
-task :release => [ :publish ]
+task release: [ :publish ]

data/lib/arachni/rpc.rb

@@ -6,12 +6,8 @@
 
 =end
 
-require 'set'
-
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'version' )
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'exceptions' )
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'message' )
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'request' )
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'response' )
-require File.join( File.expand_path( File.dirname( __FILE__ ) ), 'rpc', 'remote_object_mapper' )
+require 'arachni/reactor'
 
+%w(version exceptions message request response proxy protocol client server).each do |f|
+    require_relative "rpc/#{f}"
+end

data/lib/arachni/rpc/client.rb

@@ -0,0 +1,236 @@
+=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 Arachni
+module RPC
+
+require_relative 'client/handler'
+
+# Simple RPC client capable of:
+#
+# * TLS encryption.
+# * Asynchronous and synchronous requests.
+# * Handling remote asynchronous calls that defer their result.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Client
+
+    # Default amount of connections to maintain in the re-use pool.
+    DEFAULT_CONNECTION_POOL_SIZE = 1
+
+    # @return   [Hash]
+    #   Options hash.
+    attr_reader :opts
+
+    # @return   [Integer]
+    #   Amount of connections in the pool.
+    attr_reader :connection_count
+
+    # @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',
+    #
+    #        :serializer => Marshal,
+    #
+    #        :max_retries => 0,
+    #
+    #        # 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    [Integer]   :connection_pool_size (1)
+    #   Amount of connections to keep open.
+    # @option   opts    [String]    :token  Optional authentication token.
+    # @option   opts    [.dump, .load]      :serializer (YAML)
+    #   Serializer to use for message transmission.
+    # @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.merge( role: :client )
+        @token = @opts[:token]
+
+        @host, @port = @opts[:host], @opts[:port].to_i
+        @socket = @opts[:socket]
+
+        if !@socket && !(@host || @port)
+            fail ArgumentError, 'Needs either a :socket or :host and :port options.'
+        end
+
+        @port = @port.to_i
+
+        if @host && @port <= 0
+            fail ArgumentError, "Invalid port: #{@port}"
+        end
+
+        @pool_size = @opts[:connection_pool_size] || DEFAULT_CONNECTION_POOL_SIZE
+
+        @reactor = Reactor.global
+
+        @connections      = @reactor.create_queue
+        @connection_count = 0
+    end
+
+    # Connection factory, will re-use or create new connections as needed to
+    # accommodate the workload.
+    #
+    # @param    [Block] block
+    #   Block to be passed a {Handler connection}.
+    #
+    # @return   [Boolean]
+    #   `true` if a new connection had to be established, `false` if an existing
+    #   one was re-used.
+    def connect( &block )
+        if @connections.empty? && @connection_count < @pool_size
+            opts = @socket ? @socket : [@host, @port]
+            block.call @reactor.connect( *[opts, Handler, @opts.merge( client: self )].flatten )
+            increment_connection_counter
+            return true
+        end
+
+        pop_block = proc do |conn|
+            # Some connections may have died while they were waiting in the
+            # queue, get rid of them and start all over in case the queue has
+            # been emptied.
+            if !conn.done?
+                connection_failed conn
+                connect( &block )
+                next
+            end
+
+            block.call conn
+        end
+
+        @connections.pop( &pop_block )
+
+        false
+    end
+
+    # Close all connections.
+    def close
+        @reactor.on_tick do |task|
+            @connections.pop(&:close_without_retry)
+            task.done if @connections.empty?
+        end
+    end
+
+    def increment_connection_counter
+        @connection_count += 1
+    end
+
+    # {Handler#done? Finished} {Handler}s push themselves here to be re-used.
+    #
+    # @param    [Handler]   connection
+    def push_connection( connection )
+        @connections << connection
+    end
+
+    # Handles failed connections.
+    #
+    # @param    [Handler]   connection
+    def connection_failed( connection )
+        @connection_count -= 1
+        connection.close_without_retry
+    end
+
+    # Calls a remote method and grabs the result.
+    #
+    # There are 2 ways to perform a call, async (non-blocking) and sync (blocking).
+    #
+    # @example To perform an async call you need to provide a block to handle the result.
+    #
+    #    server.call( 'handler.method', arg1, arg2 ) do |res|
+    #        do_stuff( res )
+    #    end
+    #
+    # @example To perform a sync (blocking), call without a block.
+    #
+    #    res = server.call( 'handler.method', arg1, arg2 )
+    #
+    # @param    [String]    msg
+    #   RPC message in the form of `handler.method`.
+    # @param    [Array]     args
+    #   Collection of arguments to be passed to the method.
+    # @param    [Block]      block
+    def call( msg, *args, &block )
+        req = Request.new(
+            message:  msg,
+            args:     args,
+            callback: block,
+            token:    @token
+        )
+
+        block_given? ? call_async( req ) : call_sync( req )
+    end
+
+    private
+
+    def set_exception( req, e )
+        msg = @socket ? " for '#{@socket}'." : " for '#{@host}:#{@port}'."
+
+        exc = (e.is_a?( Reactor::Connection::Error::SSL ) ?
+                Exceptions::SSLPeerVerificationFailed : Exceptions::ConnectionError
+                ).new( e.to_s + msg )
+
+        exc.set_backtrace e.backtrace
+        req.callback.call exc
+    end
+
+    def call_async( req, &block )
+        req.callback = block if block_given?
+
+        begin
+            connect do |connection|
+                error = (connection.is_a?( Exception ) and connection) || connection.error
+                next set_exception( req, error ) if error
+
+                connection.send_request( req )
+            end
+        rescue => e
+            set_exception( req, e )
+        end
+    end
+
+    def call_sync( req )
+        # If we're in the Reactor thread use a Fiber and if we're not use a Thread.
+        if @reactor.in_same_thread?
+            fail 'Cannot perform synchronous calls when running in the ' +
+                     "#{Arachni::Reactor} loop."
+        end
+
+        q = Queue.new
+        call_async( req ) { |obj| q << obj }
+        ret = q.pop
+
+        raise ret if ret.is_a?( Exception )
+
+        ret
+    end
+
+end
+
+end
+end