toq 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f490887ff8d26a2e18e5c010e286a6fc48ad85a9955471909496d78158ce4fc
+  data.tar.gz: f5c0d6ecf126970506d46a0416fd7effedbd590e99a9a5cb7b1601f0898af06d
+SHA512:
+  metadata.gz: 760fc6a92f3162b42e91c0c62f217431745887699f743182f91e8265a2557c02b16e8a5f7defbad2cb4ed06559fb9c204d3e49393feb3001793a740d975c02d3
+  data.tar.gz: b91e5bafb6631ecc1e09d777b2144f54735b7c6975422bb9c1b359a2a39d2294c6163142196288bc84ffec56c004209346e6e58cd5747e8167570fbb3110ef89

data/CHANGELOG.md

@@ -0,0 +1 @@
+# ChangeLog

data/LICENSE.md

@@ -0,0 +1,29 @@
+# License
+
+    Copyright (C) 2022, Ecsypno <https://ecsypno.com/>
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification,
+    are permitted provided that the following conditions are met:
+
+        * Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+        * Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+
+        * Neither the name of the copyright holder nor the names of its contributors
+          may be used to endorse or promote products derived from this software
+          without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,68 @@
+# Toq
+
+<table>
+    <tr>
+        <th>Version</th>
+        <td>0.0.1</td>
+    </tr>
+    <tr>
+        <th>Github page</th>
+        <td><a href="http://github.com/qadron/toq">http://github.com/qadron/toq</a></td>
+     <tr/>
+    <tr>
+        <th>Code Documentation</th>
+        <td><a href="http://rubydoc.info/github/qadron/toq/">http://rubydoc.info/github/qadron/toq/</a></td>
+    </tr>
+    <tr>
+       <th>Author</th>
+       <td><a href="mailto:tasos.laskos@gmail.com">Tasos Laskos</a></td>
+    </tr>
+    <tr>
+        <th>Copyright</th>
+        <td>2022 <a href="https://ecsypno.com">Ecsypno</a></td>
+    </tr>
+    <tr>
+        <th>License</th>
+        <td><a href="file.LICENSE.html">3-clause BSD</a></td>
+    </tr>
+</table>
+
+## Synopsis
+
+Toq is a simple and lightweight Remote Procedure Call protocol and implementation.
+
+This implementation is based on [Raktr](https://github.com/qadron/raktr).
+
+## Features
+
+ - 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
+
+    gem install toq
+
+## Running the Specs
+
+    bundle install
+    rake spec
+
+## Protocol specifications
+
+You can find the RPC protocol specification at the
+[Wiki](https://github.com/Arachni/arachni-rpc/wiki).
+
+## License
+
+Toq is provided under the 3-clause BSD license.
+See the `LICENSE` file for more information.

data/Rakefile

@@ -0,0 +1,53 @@
+=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 'rubygems'
+require File.expand_path( File.dirname( __FILE__ ) ) + '/lib/toq/version'
+
+begin
+    require 'rspec'
+    require 'rspec/core/rake_task'
+
+    RSpec::Core::RakeTask.new
+rescue
+end
+
+task default: [ :build, :spec ]
+
+desc 'Generate docs'
+task :docs do
+    outdir = "../toq"
+    sh "rm -rf #{outdir}"
+    sh "mkdir -p #{outdir}"
+
+    sh "yardoc -o #{outdir}"
+
+    sh "rm -rf .yardoc"
+end
+
+desc 'Clean up'
+task :clean do
+    sh 'rm *.gem || true'
+end
+
+desc 'Build the toq gem.'
+task build: [ :clean ] do
+    sh 'gem build toq.gemspec'
+end
+
+desc 'Build and install the toq gem.'
+task install: [ :build ] do
+    sh "gem install toq-#{Toq::VERSION}.gem"
+end
+
+desc 'Push a new version to Rubygems'
+task publish: [ :build ] do
+    sh "git tag -a v#{Toq::VERSION} -m 'Version #{Toq::VERSION}'"
+    sh "gem push toq-#{Toq::VERSION}.gem"
+end
+task release: [ :publish ]

data/lib/toq/client/handler.rb

@@ -0,0 +1,165 @@
+=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
+class Client
+
+# Transmits {Request} objects and calls callbacks once an {Response} is received.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@arachni-scanner.com>
+class Handler < Raktr::Connection
+    include Toq::Protocol
+
+    # 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
+
+    # @return   [Exceptions::ConnectionError]
+    attr_reader :error
+
+    # 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
+    end
+
+    # Sends an RPC request (i.e. performs an RPC call) and sets {#status}
+    # to `:pending`.
+    #
+    # @param    [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    [Toq::Response]    res
+    def receive_response( res )
+        if res.exception?
+            res.obj = Exceptions.from_response( res )
+        end
+
+        @request.callback.call( res.obj ) if @request.callback
+    ensure
+        @request = nil # Help the GC out.
+        @error   = nil # Help the GC out.
+        @status  = :done
+
+        @opts[:tries] = @tries = 0
+        @client.push_connection self
+    end
+
+    # Handles closed connections, cleans up the SSL session, retries (if
+    # necessary) and sets {#status} to `:closed`.
+    #
+    # @private
+    def on_close( reason )
+         if @request
+             # 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?
+                     retry_request
+                 else
+                     @error = e = Exceptions::ConnectionError.new( "Connection closed [#{reason}]" )
+                     @request.callback.call( e )
+                     @client.connection_failed self
+                 end
+
+                 return
+             end
+         else
+             @error = reason
+             @client.connection_failed self
+         end
+
+        close_without_retry
+    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_without_callback
+    end
+
+    private
+
+    # Converts incoming hash objects to {Response} objects and calls
+    # {#receive_response}.
+    #
+    # @param    [Hash]      obj
+    def receive_object( obj )
+        receive_response( Response.new( obj ) )
+    end
+
+    def retry_request
+        opts = @opts.dup
+        opts[:tries] += 1
+
+        req = @request.dup
+
+        # The connection will be detached soon, keep a separate reference to
+        # the reactor.
+        reactor = @reactor
+
+        @tries += 1
+        reactor.delay( 0.2 ) do
+            address = opts[:socket] ? opts[:socket] : [opts[:host], opts[:port]]
+            reactor.connect( *[address, self.class, opts ].flatten ).send_request( req )
+        end
+
+        close_without_retry
+    end
+
+    def retry?
+        @tries < @max_retries
+    end
+
+end
+
+end
+end

data/lib/toq/client.rb

@@ -0,0 +1,249 @@
+=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
+
+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 = Raktr.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 )
+        ensure_reactor_running
+
+        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
+        ensure_reactor_running
+
+        @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 )
+        ensure_reactor_running
+
+        @connections << connection
+    end
+
+    # Handles failed connections.
+    #
+    # @param    [Handler]   connection
+    def connection_failed( connection )
+        ensure_reactor_running
+
+        @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 )
+        ensure_reactor_running
+
+        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?( Raktr::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 ' +
+                     "#{Raktr} loop."
+        end
+
+        q = Queue.new
+        call_async( req ) { |obj| q << obj }
+        ret = q.pop
+
+        raise ret if ret.is_a?( Exception )
+
+        ret
+    end
+
+    def ensure_reactor_running
+        return if @reactor.running?
+        @reactor.run_in_thread
+    end
+
+end
+
+end