xrbp 0.0.1 → 0.1.0

data/lib/xrbp/webclient/plugins.rb

@@ -0,0 +1,8 @@
+module XRBP
+  module WebClient
+    include PluginRegistry
+  end # module WebClient
+end # module XRPB
+
+require_relative './plugins/result_parser'
+require_relative './plugins/autoretry'

data/lib/xrbp/webclient/plugins/autoretry.rb

@@ -0,0 +1,54 @@
+module XRBP
+  module WebClient
+    module Plugins
+      # Plugin to automatically retry WebClient Connection requests
+      # multiple times.
+      # 
+      # If no max_tries are specified, requests will be tried indefinitely.
+      # Optionally configured interval to wait between retries.
+      #
+      # @example retrying request:
+      #   connection = WebClient::Connection.new
+      #   connection.add_plugin :autoretry
+      #
+      #   connection.max_tries = 3
+      #   connection.interval  = 1
+      #   connection.timeout   = 1
+      #
+      #   connection.url = "http://doesnt.exist"
+      #   connection.perform
+      class AutoRetry < PluginBase
+        attr_accessor :interval, :max_tries
+
+        def initialize(connection)
+          super(connection)
+          @interval   = 3
+          @max_tries  = nil
+          @retry_num  = 0
+        end
+
+        def added
+          plugin = self
+          connection.define_instance_method(:retry_interval=) do |i|
+            plugin.interval = i
+          end
+
+          connection.define_instance_method(:max_retries=) do |i|
+            plugin.max_tries = i
+          end
+        end
+
+        def handle_error
+          @retry_num += 1
+          return nil if connection.force_quit? ||
+                        (!@max_tries.nil? && @retry_num > @max_tries)
+
+          connection.rsleep(@interval)
+          connection.perform
+        end
+      end # class AutoRetry
+
+      WebClient.register_plugin :autoretry, AutoRetry
+    end # module Plugins
+  end # module WebClient
+end # module XRBP

data/lib/xrbp/webclient/plugins/result_parser.rb

@@ -0,0 +1,23 @@
+module XRBP
+  module WebClient
+    module Plugins
+      # Plugin to automatically parse and convert webclient results,
+      # before returning.
+      #
+      # @example parse json
+      #   connection = WebClient::Connection.new
+      #   connection.add_plugin :result_parser
+      #
+      #   connection.parse_results do |res|
+      #     JSON.parse(res)
+      #   end
+      #
+      #   connection.url = "https://data.ripple.com/v2/gateways"
+      #   connection.perform
+      class ResultParser < ResultParserBase
+      end
+
+      WebClient.register_plugin :result_parser, ResultParser
+    end # module Plugins
+  end # module WebClient
+end # module XRBP

data/lib/xrbp/websocket/client.rb

@@ -2,8 +2,12 @@ require 'websocket'
 
 module XRBP
   module WebSocket
+    # Managed socket connection lifecycle and read/write operations
+    #
+    # @private
     class Client
       include EventEmitter
+      include Terminatable
 
       attr_reader :url, :options
 
@@ -12,18 +16,28 @@ module XRBP
         @options = options
 
         @handshaked = false
-        @closed = false
+        @closed = true
+        @completed = true
       end
 
       def connect
-        emit :connecting
+        emit_signal :connecting
+
         @closed = false
+        @completed = false
         socket.connect
         handshake!
-        @thread = poll
+
+        start_read
+
         self
       end
 
+      # Add job to internal thread pool.
+      def add_work(&bl)
+        pool.post &bl
+      end
+
       ###
 
       def open?
@@ -34,33 +48,53 @@ module XRBP
         !!@closed
       end
 
+      def completed?
+        !!@completed
+      end
+
+      # Allow close to be run via seperate thread so
+      # as not to block caller
+      def async_close(err=nil)
+        Thread.new { close(err)  }
+      end
+
       def close(err=nil)
         return if closed?
 
         # XXX set closed true first incase callbacks need to check this
         @closed = true
+        @handshake = nil
+        @handshaked = false
+
+        terminate!
 
         send_data nil, :type => :close unless socket.pipe_broken
-        emit :close, err
+        emit_signal :close, err
 
-      ensure
-        # Always set closed true
-        @closed = true
         socket.close if socket
-        @handshake = nil
-        @handshaked = false
         @socket = nil
-        #Thread.kill @thread if @thread
-        @thread.join if @thread && Thread.current != @thread
+
+        pool.shutdown
+        pool.wait_for_termination
+        @pool = nil
+
+        @completed = true
         emit :completed
+        self
       end
 
+      private
+
       ###
 
       def socket
         @socket ||= Socket.new self
       end
 
+      def pool
+        @pool ||= Concurrent::CachedThreadPool.new
+      end
+
       ###
 
       def handshake
@@ -83,43 +117,70 @@ module XRBP
 
       ###
 
+      def data_frame(data, type)
+        ::WebSocket::Frame::Outgoing::Client.new(:data => data,
+                                                 :type => type,
+                                              :version => handshake.version)
+      end
+
+      public
+
       def send_data(data, opt={:type => :text})
         return if !handshaked? || closed?
 
-        frame = ::WebSocket::Frame::Outgoing::Client.new(:data => data,
-                                                         :type => opt[:type],
-                                                      :version => handshake.version)
-
         begin
+          frame = data_frame(data, opt[:type])
           socket.write_nonblock(frame.to_s)
 
         rescue Errno::EPIPE, OpenSSL::SSL::SSLError => e
-          close(e)
+          async_close(e)
         end
       end
 
-      def poll
-        return Thread.new(socket) do |socket|
+      private
+
+      def start_read
+        add_work do
           frame = ::WebSocket::Frame::Incoming::Client.new
-          emit :open
+          emit_signal :open
 
-          until closed? do
+          cl = trm = eof = false
+          until (trm = terminate?) || (cl = closed?) do
             begin
               socket.read_next(frame)
 
               if msg = frame.next
-                emit :message, msg
+                emit_signal :message, msg
                 frame = ::WebSocket::Frame::Incoming::Client.new
               end
 
             rescue EOFError => e
-              emit :error, e
-              close(e)
+              emit_signal :error, e
+              eof = e
 
             rescue => e
-              emit :error, e
+              emit_signal :error, e
             end
           end
+
+          # ... is this right?:
+          async_close(eof) if !!eof && !cl && !trm
+        end
+      end
+
+      def emit_signal(*args)
+        # TODO add args to queue, and in add_work task, pull 1 item off queue
+        #      & emit it (to enforce signal order)
+        begin
+          add_work do
+            emit *args
+          end
+
+          # XXX: handle race condition where connection is closed
+          #      between calling emit_signal and pool.post (handle
+          #      error, otherwise a mutex would be needed)
+        rescue Concurrent::RejectedExecutionError => e
+          raise e unless closed?
         end
       end
     end # class Client

data/lib/xrbp/websocket/cmds/account_info.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The account_info command retrieves information about an
+      # account, its activity, and its XRP balance.
+      #
+      # https://developers.ripple.com/account_info.html
       class AccountInfo < Command
         attr_accessor :account, :args
 

data/lib/xrbp/websocket/cmds/account_lines.rb

@@ -1,6 +1,11 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The account_lines method returns information about an
+      # account's trust lines, including balances in all non-XRP
+      # currencies and assets
+      #
+      # https://developers.ripple.com/account_lines.html
       class AccountLines < Command
         include Paginated
 

data/lib/xrbp/websocket/cmds/account_objects.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The account_objects command returns the raw ledger format for
+      # all objects owned by an account
+      #
+      # https://developers.ripple.com/account_objects.html
       class AccountObjects < Command
         include Paginated
 

data/lib/xrbp/websocket/cmds/account_offers.rb

@@ -1,6 +1,11 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The account_offers method retrieves a list of offers made
+      # by a given account that are outstanding as of a particular
+      # ledger version.
+      #
+      # https://developers.ripple.com/account_offers.html
       class AccountOffers < Command
         include Paginated
 

data/lib/xrbp/websocket/cmds/account_tx.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The account_tx method retrieves a list of transactions
+      # that involved the specified account.
+      #
+      # https://developers.ripple.com/account_tx.html
       class AccountTx < Command
         attr_accessor :account, :args
 

data/lib/xrbp/websocket/cmds/book_offers.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The book_offers method retrieves a list of offers, also known as
+      # the order book , between two currencies
+      #
+      # https://developers.ripple.com/book_offers.html
       class BookOffers < Command
         include Paginated
 

data/lib/xrbp/websocket/cmds/ledger.rb

@@ -1,6 +1,9 @@
 module XRBP
   module WebSocket
     module Cmds
+      # Retrieve information about the public ledger
+      #
+      # https://developers.ripple.com/ledger.html
       class Ledger < Command
         attr_accessor :id, :args
 

data/lib/xrbp/websocket/cmds/ledger_entry.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The ledger_entry method returns a single ledger object
+      # from the XRP Ledger in its raw format
+      #
+      # https://developers.ripple.com/ledger_entry.html
       class LedgerEntry < Command
         def initialize(args={})
           @args = args

data/lib/xrbp/websocket/cmds/paginated.rb

@@ -1,8 +1,11 @@
-require 'active_support/core_ext/hash/except'
+require 'xrbp/core_ext'
 
 module XRBP
   module WebSocket
     module Cmds
+      # Helper mixin facilitating paginated command retrieval.
+      #
+      # @private
       module Paginated
         attr_reader :prev_cmd
 

data/lib/xrbp/websocket/cmds/server_info.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The server_info command asks the server for a human-readable version
+      # of various information about the rippled server being queried.
+      #
+      # https://developers.ripple.com/server_info.html
       class ServerInfo < Command
         def initialize
           super({'command' => 'server_info'})

data/lib/xrbp/websocket/cmds/subscribe.rb

@@ -1,6 +1,10 @@
 module XRBP
   module WebSocket
     module Cmds
+      # The subscribe method requests periodic notifications
+      # from the server when certain events happen
+      #
+      # https://developers.ripple.com/subscribe.html
       class Subscribe < Command
         attr_accessor :args
 

data/lib/xrbp/websocket/command.rb

@@ -4,6 +4,7 @@ module XRBP
   module WebSocket
     class Command < Message
       attr_accessor :id
+      attr_reader :json
 
       def initialize(data)
         @@id ||= 0
@@ -12,8 +13,18 @@ module XRBP
         json = Hash[data]
         json['id'] = id
 
+        @json = json
+
         super(json.to_json)
       end
+
+      def requesting
+        @json[:command] || @json["command"]
+      end
+
+      def requesting?(tgt)
+        requesting.to_s == tgt.to_s
+      end
     end # class Command
   end # module WebSocket
 end # module XRBP

data/lib/xrbp/websocket/connection.rb

@@ -1,10 +1,21 @@
-require_relative './has_plugin'
+require_relative '../thread_registry'
 
 module XRBP
   module WebSocket
+    # Primary websocket interface, use Connection to perform
+    # websocket requests.
+    #
+    # @example retrieve data via a websocket
+    #   connection = WebSocket::Connection.new "wss://s1.ripple.com:443"
+    #   puts connection.send_data('{"command" : "server_info"}')
     class Connection
       include EventEmitter
       include HasPlugin
+      include ThreadRegistry
+
+      def plugin_namespace
+        WebSocket
+      end
 
       attr_reader :url
       attr_accessor :parent
@@ -12,35 +23,65 @@ module XRBP
       def initialize(url)
         @url        = url
         @force_quit = false
+
+        yield self if block_given?
       end
 
       ###
 
+      # Initiate new client connection
       def connect
         client.connect
       end
 
+      # Return next connection of parent if applicable
+      #
+      # @private
       def next_connection(prev)
         return nil unless !!parent
         parent.next_connection(prev)
       end
 
+      # Add work to the internal client thread pool
+      #
+      # @private
+      def add_work(&bl)
+        client.add_work &bl
+      end
+
+      # Indicates the connection is  initialized
       def initialized?
         !!@client
       end
 
+      # Indicates the connection is open
       def open?
         initialized? && client.open?
       end
 
+      # Indicates the connection is closed
+      # (may not be completed)
       def closed?
         !open?
       end
 
+      # Indicates if connection is completely
+      # closed and cleaned up
+      def completed?
+        client.completed?
+      end
+
+      # Close the connection, blocking until completed
       def close!
         client.close if open?
       end
 
+      # Close in a non-blocking way, and immediately return.
+      def async_close!
+        client.async_close if open?
+      end
+
+      # Send raw data via this connection
       def send_data(data)
         client.send_data(data)
       end
@@ -51,27 +92,16 @@ module XRBP
         @force_quit
       end
 
+      # Immediately terminate the connection and all related operations
       def force_quit!
         @force_quit = true
         wake_all
-      end
-
-      def thread_registry
-        @thread_registry ||= Concurrent::Array.new
-      end
-
-      def rsleep(t)
-        thread_registry << Thread.current
-        sleep(t)
-        thread_registry.delete(Thread.current)
-      end
-
-      def wake_all
-        thread_registry.each { |th| th.wakeup }
+        # TODO immediate terminate socket connection
       end
 
       ###
 
+      # Block until connection is open
       def wait_for_open
         return unless initialized?
 
@@ -80,6 +110,7 @@ module XRBP
         } until force_quit? || open?
       end
 
+      # Block until connection is closed
       def wait_for_close
         return unless initialized?
 
@@ -88,6 +119,15 @@ module XRBP
         } while !force_quit? && open?
       end
 
+      # Block until connection is completed
+      def wait_for_completed
+        return unless initialized?
+
+        state_mutex.synchronize {
+          completed_cv.wait(state_mutex, 0.1)
+        } while !force_quit? && !completed?
+      end
+
       def state_mutex
         @state_mutex ||= Mutex.new
       end
@@ -100,8 +140,13 @@ module XRBP
         @close_cv ||= ConditionVariable.new
       end
 
+      def completed_cv
+        @completed_cv ||= ConditionVariable.new
+      end
+
       ###
 
+      # @private
       def client
         @client ||= begin
           client = Client.new(@url)
@@ -109,12 +154,12 @@ module XRBP
 
           client.on :connecting do
             conn.emit :connecting
-            conn.parent.emit :connecting if conn.parent
+            conn.parent.emit :connecting, conn if conn.parent
           end
 
           client.on :open do
             conn.emit :open
-            conn.parent.emit :open if conn.parent
+            conn.parent.emit :open, conn if conn.parent
 
             conn.state_mutex.synchronize {
               conn.open_cv.signal
@@ -127,7 +172,7 @@ module XRBP
 
           client.on :close do
             conn.emit :close
-            conn.parent.emit :close if conn.parent
+            conn.parent.emit :close, conn if conn.parent
 
             conn.state_mutex.synchronize {
               conn.close_cv.signal
@@ -140,12 +185,20 @@ module XRBP
 
           client.on :completed do |err|
             conn.emit :completed
-            conn.parent.emit :completed if conn.parent
+            conn.parent.emit :completed, conn if conn.parent
+
+            conn.state_mutex.synchronize {
+              conn.completed_cv.signal
+            }
+
+            conn.plugins.each { |plg|
+              plg.completed if plg.respond_to?(:completed)
+            }
           end
 
           client.on :error do |err|
             conn.emit :error, err
-            conn.parent.emit :error, err if conn.parent
+            conn.parent.emit :error, conn, err if conn.parent
 
             conn.plugins.each { |plg|
               plg.error err if plg.respond_to?(:error)
@@ -154,7 +207,7 @@ module XRBP
 
           client.on :message do |msg|
             conn.emit :message, msg
-            conn.parent.emit :message, msg if conn.parent
+            conn.parent.emit :message, conn, msg if conn.parent
 
             conn.plugins.each { |plg|
               plg.message msg if plg.respond_to?(:message)
@@ -165,5 +218,5 @@ module XRBP
         end
       end
     end # class Connection
-  end # module WebSocket 
+  end # module WebSocket
 end # module XRBP