xrbp 0.0.1 → 0.1.0

data/lib/xrbp/websocket/message.rb

@@ -1,8 +1,10 @@
 module XRBP
   module WebSocket
+    # Raw data which to write to websocket and mechanisms
+    # which to track and manage response state.
     class Message
-      attr_reader :result, :time
-      attr_accessor :connection
+      attr_reader :result
+      attr_accessor :time, :connection
 
       def initialize(data)
         @data = data
@@ -19,6 +21,7 @@ module XRBP
       def signal
         @signalled = true
         @cv.signal
+        self
       end
 
       def wait

data/lib/xrbp/websocket/multi/fallback.rb

@@ -1,10 +1,8 @@
 module XRBP
   module WebSocket
+    # MultiConnection strategy where connections are tried sequentially
+    # until one is found that is open & succeeds
     class Fallback < MultiConnection
-      def initialize(*urls)
-        super(*urls)
-      end
-
       def next_connection(prev=nil)
         unless prev.nil?
           return nil if connections.last == prev

data/lib/xrbp/websocket/multi/multi_connection.rb

@@ -1,13 +1,31 @@
-require_relative '../has_plugin'
-
 module XRBP
   module WebSocket
+    # Base class facilitating transparent multiple
+    # connection dispatching. This provides mechanism which
+    # to instantiate multiple WebSocket::Connection instances
+    # proxying requests to them depending on the *next_connection*
+    # selected.
+    #
+    # This class provides all the common logic to manage
+    # multiple connections. Subclasses should override and
+    # implement *next_connection* specifying the strategy
+    # used to select the connection to use for any given
+    # request.
     class MultiConnection
       include EventEmitter
       include HasPlugin
 
+      def plugin_namespace
+        WebSocket
+      end
+
       attr_reader :connections
 
+      # MultiConnection initializer taking list of urls which
+      # to connect to
+      #
+      # @param urls [Array<String>] list of urls which to establish
+      #   connections to
       def initialize(*urls)
         @connections = []
 
@@ -20,14 +38,31 @@ module XRBP
         yield self if block_given?
       end
 
+      # Force terminate all connections
       def force_quit!
         connections.each { |c| c.force_quit! }
       end
 
+      # Close all connections
       def close!
         connections.each { |c| c.close! }
       end
 
+      # Block until all connections are openend
+      def wait_for_open
+        connections.each { |c| c.wait_for_open }
+      end
+
+      # Block until all connections are closed
+      def wait_for_close
+        connections.each { |c| c.wait_for_close }
+      end
+
+      # Block until all connections are completed
+      def wait_for_completed
+        connections.each { |c| c.wait_for_completed }
+      end
+
       alias :_add_plugin :add_plugin
 
       def add_plugin(*plg)

data/lib/xrbp/websocket/multi/parallel.rb

@@ -1,5 +1,7 @@
 module XRBP
   module WebSocket
+    # MultiConnection strategy where requests are sent to
+    # all connections in parallel.
     class Parallel < MultiConnection
       class All
         attr_accessor :connections
@@ -15,10 +17,6 @@ module XRBP
         end
       end # class All
 
-      def initialize(*urls)
-        super(*urls)
-      end
-
       def next_connection(prev=nil)
         return nil unless prev.nil?
         All.new connections

data/lib/xrbp/websocket/multi/prioritized.rb

@@ -1,10 +1,8 @@
 module XRBP
   module WebSocket
+    # MultiConnection strategy where connections are tried
+    # sequentially until one succeeds
     class Prioritized < MultiConnection
-      def initialize(*urls)
-        super(*urls)
-      end
-
       def next_connection(prev=nil)
         return nil if prev == connections.last
         return super if prev.nil?

data/lib/xrbp/websocket/multi/round_robin.rb

@@ -1,5 +1,9 @@
 module XRBP
   module WebSocket
+    # MultiConnection strategy where connections selected in
+    # a circular-round robin manner, where the next connection
+    # is always used for the next request even if the current
+    # one succeeds.
     class RoundRobin < MultiConnection
       def initialize(*urls)
         super(*urls)

data/lib/xrbp/websocket/plugins.rb

@@ -1,12 +1,6 @@
 module XRBP
   module WebSocket
-    def self.plugins
-      @plugins ||= {}
-    end
-
-    def self.register_plugin(label, cls)
-      plugins[label] = cls
-    end
+    include PluginRegistry
   end # module WebSocket
 end # module XRPB
 

data/lib/xrbp/websocket/plugins/autoconnect.rb

@@ -1,22 +1,42 @@
 module XRBP
   module WebSocket
     module Plugins
-      # Automatically reconnects on close events
-      class AutoConnect
-        attr_reader :connection
+      # Automatically connects on instantiation and reconnects
+      # on close events.
+      #
+      # @example autoconnecting
+      #   connection = WebSocket::Connection.new "wss://s1.ripple.com:443"
+      #   connection.add_plugin :autoconnect
+      #   connection.open? # => true
+      class AutoConnect < PluginBase
+        attr_accessor :reconnect_delay
 
         def initialize(connection)
-          @connection = connection
+          super(connection)
+          @reconnect_delay = nil
         end
 
         def added
+          plugin = self
+
+          connection.define_instance_method(:reconnect_delay=) do |d|
+            plugin.reconnect_delay = d
+
+            connections.each{ |c|
+              c.plugin(AutoConnect)
+               .reconnect_delay = d
+            } if self.kind_of?(MultiConnection)
+          end
+
           return if connection.kind_of?(MultiConnection)
 
           conn = connection
-
           connection.on :completed do
             connected = false
             until conn.force_quit? || connected
+              conn.rsleep(plugin.reconnect_delay) if plugin.reconnect_delay
+              next if conn.force_quit?
+
               begin
                 conn.connect
                 connected = true

data/lib/xrbp/websocket/plugins/command_dispatcher.rb

@@ -2,6 +2,11 @@ module XRBP
   module WebSocket
     module Plugins
       # Dispatch commands (based on message dispatcher)
+      #
+      # @example dispatching server info command
+      #   connection = WebSocket::Connection.new "wss://s1.ripple.com:443"
+      #   connection.add_plugin :command_dispatcher
+      #   puts connection.cmd(WebSocket::Cmds::ServerInfo.new)
       class CommandDispatcher < MessageDispatcher
         def added
           super

data/lib/xrbp/websocket/plugins/command_paginator.rb

@@ -1,20 +1,21 @@
 module XRBP
   module WebSocket
     module Plugins
-      # Handles multi-page messages
-      class CommandPaginator
-        attr_reader :connection
-
-        def initialize(connection)
-          @connection = connection
-        end
-
+      # Handles multi-page responses, automatically issuing subsequent requests
+      # when more data is available and concatinating results.
+      #
+      # This is most useful with account transaction and object lists where a
+      # single account may be associated with more data than can returned in a
+      # single result. In this case response will include pagination marker
+      # which we leverage here to retrieve all data.
+      class CommandPaginator < PluginBase
         def added
           raise "Must also include CommandDispatcher plugin" unless connection.plugin?(CommandDispatcher)
         end
 
         def unlock!(cmd, res)
           return true unless cmd.respond_to?(:paginate?) && cmd.paginate?
+          return true unless res["result"] # unlock if we cannot get result
 
           marker = res["result"]["marker"]
           page   = res["result"][cmd.page_title]

data/lib/xrbp/websocket/plugins/connection_timeout.rb

@@ -2,25 +2,39 @@ module XRBP
   module WebSocket
     module Plugins
       # Automatic disconnection if no server data in certain time
-      class ConnectionTimeout
-        attr_reader :connection
+      #
+      # @example timed out connection
+      #   connection = WebSocket::Connection.new "wss://s1.ripple.com:443"
+      #   connection.add_plugin :connection_timeout
+      #   connection.connection_timeout = 3
+      #   connection.connect
+      #   sleep(3)
+      #   connection.closed? # => true
+      class ConnectionTimeout < PluginBase
+        include Terminatable
+
         attr_accessor :connection_timeout
 
         DEFAULT_TIMEOUT = 10
 
         def initialize(connection)
-          @connection = connection
+          super(connection)
           @connection_timeout = DEFAULT_TIMEOUT
         end
 
+        def timeout?
+          Time.now - @last_msg > @connection_timeout
+        end
+
         def added
           plugin = self
           connection.define_instance_method(:connection_timeout=) do |t|
             plugin.connection_timeout = t
 
-            self.plugins.find { |plg|
-              plg.is_a?(ConnectionTimeout)
-            }.connection_timeout = t if self.kind_of?(MultiConnection)
+            connections.each{ |c|
+              c.plugin(ConnectionTimeout)
+               .connection_timeout = t
+            } if self.kind_of?(MultiConnection)
           end
         end
 
@@ -29,22 +43,19 @@ module XRBP
         end
 
         def opened
-          @thread = Thread.new {
+          connection.add_work do
             @last_msg = Time.now
-            until connection.force_quit? ||
-                  connection.closed?     ||
-                  Thread.current != @thread
-              if Time.now - @last_msg > @connection_timeout
-                connection.close!
-              end
-
+            until terminate?             ||
+                  connection.force_quit? ||
+                  connection.closed?
+              connection.async_close! if timeout?
               connection.rsleep(0.1)
             end
-          }
+          end
         end
 
         def closed
-          @thread.join unless @thread == Thread.current
+          terminate!
         end
       end # class ConnectionTimeout
 

data/lib/xrbp/websocket/plugins/message_dispatcher.rb

@@ -1,15 +1,30 @@
 module XRBP
   module WebSocket
     module Plugins
-      # Dispatch messages & wait for responses (w/ optional timeout)
-      class MessageDispatcher
-        attr_reader :connection, :messages
-        attr_accessor :message_timeout
+      # Dispatch messages & wait for responses (w/ optional timeout).
+      # This module allows the client to track messages sent to the server,
+      # waiting for responses up to a maximum time. An overridable callback
+      # method is provided to match responses to messages. Most often the
+      # end-user will not use this plugin directly but rather through
+      # CommandDispatcher which inherits it / extends it to issue and
+      # track structured commands.
+      #
+      # @see CommandDispatcher
+      class MessageDispatcher < PluginBase
+        include Terminatable
+        include HasResultParsers
 
         DEFAULT_TIMEOUT = 10
 
+        def parsing_plugins
+          connection.plugins
+        end
+
+        attr_reader :messages
+        attr_accessor :message_timeout
+
         def initialize(connection)
-          @connection = connection
+          super(connection)
           @message_timeout = DEFAULT_TIMEOUT
           @messages = []
         end
@@ -20,9 +35,10 @@ module XRBP
           connection.define_instance_method(:message_timeout=) do |t|
             plugin.message_timeout = t
 
-            self.plugins.find { |plg|
-              plg.kind_of?(MessageDipsatcher)
-            }.message_timeout = t if self.kind_of?(MultiConnection)
+            connections.each{ |c|
+              c.plugin(MessageDispatcher)
+               .message_timeout = t
+            } if self.kind_of?(MultiConnection)
           end
 
           connection.define_instance_method(:msg) do |msg, &bl|
@@ -30,11 +46,19 @@ module XRBP
 
             msg = Message.new(msg) unless msg.kind_of?(Message)
             msg.connection = self
+            msg.time = Time.now
             msg.bl = bl if bl
 
             unless self.open?
-              msg.bl.call nil if msg.bl
-              return nil
+              if plugin.try_next(msg)
+                return nil if bl
+                       msg.wait
+                return msg.result
+
+              else
+                msg.bl.call nil if bl
+                return nil
+              end
             end
 
             plugin.messages << msg
@@ -47,9 +71,7 @@ module XRBP
           end
 
           connection.on :close do
-            plugin.messages.each { |msg|
-              plugin.cancel_message(msg)
-            }
+            plugin.cancel_all_messages
           end unless connection.kind_of?(MultiConnection)
         end
 
@@ -68,14 +90,6 @@ module XRBP
           }
         end
 
-        # Allows plugins to convert results
-        def parse_result(res)
-          connection.plugins.each { |plg|
-            res = plg.parse_result(res) if plg != self && plg.respond_to?(:parse_result)
-          }
-          res
-        end
-
         def message(res)
           req, res = match_message(res)
           return unless req
@@ -84,10 +98,9 @@ module XRBP
           return unless unlock!(req, res)
 
           begin
-            res = parse_result(res)
+            res = parse_result(res, req)
           rescue Exception => e
-            if conn = connection.next_connection(req.connection)
-              conn.msg(req, &req.bl)
+            if try_next(req)
               return
 
             else
@@ -98,6 +111,14 @@ module XRBP
           req.bl.call(res)
         end
 
+        def try_next(msg)
+          conn = connection.next_connection(msg.connection)
+          return false unless !!conn
+          messages.delete(msg)
+          conn.msg(msg, &msg.bl)
+          true
+        end
+
         def cancel_message(msg)
           connection.state_mutex.synchronize {
             messages.delete(msg)
@@ -105,33 +126,42 @@ module XRBP
           }
         end
 
+        def cancel_all_messages
+          messages.each { |msg|
+            cancel_message(msg)
+          }
+        end
+
+        public
+
         def opened
-          @timeout_thread = Thread.new {
+          connection.add_work do
             # XXX remove force_quit? condition check from this loop,
             #     so we're sure messages always timeout, even on force quit.
             #     Always ensure close! is called after websocket is no longer
             #     being used!
-            until connection.closed? || Thread.current != @timeout_thread
+            until terminate? || connection.closed?
               now = Time.now
               tmsgs = Array.new(messages)
               tmsgs.each { |msg|
                 if now - msg.time > @message_timeout
                   connection.emit :timeout, msg
-                  cancel_message(msg)
+
+                  cancel_message(msg) unless try_next(msg)
 
                   # XXX manually close the connection as
                   #     a broken pipe will not stop websocket polling
-                  connection.close!
+                  connection.async_close!
                 end
               }
 
               connection.rsleep(0.1)
             end
-          }
+          end
         end
 
         def closed
-          @timeout_thread.join unless @timeout_thread == Thread.current
+          terminate!
         end
       end # class MessageDispatcher