ione-rpc 1.0.0.pre2 → 1.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c7643bab20779d92db259349ee30689f27f00ca
-  data.tar.gz: ac4e876e133758cc94c5e52682685865225d7cdc
+  metadata.gz: 98f7be7547ebdcd263f54d286682869bd629dfdc
+  data.tar.gz: 6d331deff1f746ce7c69f3914f9527f115701d08
 SHA512:
-  metadata.gz: 54903ddee404d09c58056af6e1766d8d4c2323037cbfdfac42c66c82ad11f152425fc542eab87adf05ea4ef67afb32e351e011ff906b4329edc2f1ba0af4b49e
-  data.tar.gz: cfc8c07ab978079837a309b736505031ca422441c6c1083d81a23e55a82a0729528fb3c9874819ce5a9755bc4a6711d0946bdfcc64a1298db78fac5e167ae86a
+  metadata.gz: 4ecab7afd0cc50ecfcd9475d8f2b04da77aac64b063e022b29498556241e0bddd64329291fb2c64299cc670d22c9368203c4cb66c5ab5113d4aeb2bac035bc2f
+  data.tar.gz: 33a712ea45a402f0f5fd501fc3b4eb14af603c56c1496424512252e2c387f9801a0fc8a6b2d91e45dc25e45f6c70a50939bf60222ad16211b1e4f44c59695854

data/lib/ione/rpc/client.rb

@@ -48,7 +48,36 @@ module Ione
 
       # A client is connected when it has at least one open connection.
       def connected?
-        @lock.synchronize { @connections.any? }
+        @lock.lock
+        @connections.any?
+      ensure
+        @lock.unlock
+      end
+
+      # Returns an array of info and statistics about the currently open connections.
+      #
+      # Each open connection is represented by a hash which includes the keys
+      #
+      # * `:host` and `:port`
+      # * `:max_channels`: the maximum number of messages to send concurrently
+      # * `:active_channels`: the number of sent messages that have not yet
+      #   received a response
+      # * `:queued_messages`: the number of messages that couldn't be sent
+      #   immediately because all channels were occupied and thus had to be queued.
+      # * `:sent_messages`: the total number of messages sent since the connection
+      #   was opened
+      # * `:received_responses`: the total number of responses received since
+      #   the connection was opened
+      # * `:timeouts`: the number of sent messages that did not receive a response
+      #   before their timeout expired
+      #
+      # @return [Array<Hash>] an array of hashes that each contain info and
+      #   statistics from an open connection.
+      def connection_stats
+        @lock.lock
+        @connections.map(&:stats)
+      ensure
+        @lock.unlock
       end
 
       # Start the client and connect to all hosts. This also starts the IO
@@ -150,7 +179,14 @@ module Ione
       #   error response – that is protocol specific and up to the implementation
       #   to handle), or when there was no connection open.
       def send_request(request, connection=nil, timeout=nil)
-        connection = connection || @lock.synchronize { choose_connection(@connections, request) }
+        unless connection
+          @lock.lock
+          begin
+            connection = choose_connection(@connections, request)
+          ensure
+            @lock.unlock
+          end
+        end
         if connection
           f = connection.send_message(request, timeout)
           f = f.fallback do |error|

data/lib/ione/rpc/client_peer.rb

@@ -14,22 +14,46 @@ module Ione
         @channels = [nil] * max_channels
         @queue = []
         @encode_eagerly = @codec.recoding?
+        @sent_messages = 0
+        @received_responses = 0
+        @timeouts = 0
+      end
+
+      def stats
+        @lock.lock
+        {
+          :host => @host,
+          :port => @port,
+          :max_channels => @channels.size,
+          :active_channels => @channels.size - @channels.count(nil),
+          :queued_messages => @queue.size,
+          :sent_messages => @sent_messages,
+          :received_responses => @received_responses,
+          :timeouts => @timeouts,
+        }
+      ensure
+        @lock.unlock
       end
 
       def send_message(request, timeout=nil)
         promise = Ione::Promise.new
-        channel = @lock.synchronize do
-          take_channel(promise)
+        channel = nil
+        @lock.lock
+        begin
+          channel = take_channel(promise)
+          @sent_messages += 1 if channel
+        ensure
+          @lock.unlock
         end
         if channel
           @connection.write(@codec.encode(request, channel))
         else
-          @lock.synchronize do
-            if @encode_eagerly
-              @queue << [@codec.encode(request, -1), promise]
-            else
-              @queue << [request, promise]
-            end
+          pair = [@encode_eagerly ? @codec.encode(request, -1) : request, promise]
+          @lock.lock
+          begin
+            @queue << pair
+          ensure
+            @lock.unlock
           end
         end
         if timeout
@@ -37,6 +61,7 @@ module Ione
             unless promise.future.completed?
               error = Rpc::TimeoutError.new('No response received within %ss' % timeout.to_s)
               promise.fail(error)
+              @timeouts += 1
             end
           end
         end
@@ -46,10 +71,14 @@ module Ione
       private
 
       def handle_message(response, channel)
-        promise = @lock.synchronize do
+        promise = nil
+        @lock.lock
+        begin
           promise = @channels[channel]
           @channels[channel] = nil
-          promise
+          @received_responses += 1 if promise
+        ensure
+          @lock.unlock
         end
         if promise && !promise.future.completed?
           promise.fulfill(response)
@@ -58,24 +87,26 @@ module Ione
       end
 
       def flush_queue
-        @lock.synchronize do
-          count = 0
-          max = @queue.size
-          while count < max
-            request, promise = @queue[count]
-            if (channel = take_channel(promise))
-              if @encode_eagerly
-                @connection.write(@codec.recode(request, channel))
-              else
-                @connection.write(@codec.encode(request))
-              end
-              count += 1
+        @lock.lock
+        count = 0
+        max = @queue.size
+        while count < max
+          request, promise = @queue[count]
+          if (channel = take_channel(promise))
+            if @encode_eagerly
+              @connection.write(@codec.recode(request, channel))
             else
-              break
+              @connection.write(@codec.encode(request))
             end
+            count += 1
+          else
+            break
           end
-          @queue = @queue.drop(count)
         end
+        @sent_messages += count
+        @queue = @queue.drop(count)
+      ensure
+        @lock.unlock
       end
 
       def take_channel(promise)

data/lib/ione/rpc/codec.rb

@@ -2,10 +2,21 @@
 
 module Ione
   module Rpc
+    CodecError = Class.new(StandardError)
+
     # Codecs are used to encode and decode the messages sent between the client
     # and server. Codecs must be able to decode frames in a streaming fashion,
     # i.e. frames that come in pieces.
     #
+    # Codecs can be configured to compress frame bodies by giving them a
+    # compressor. A compressor is an object that responds to `#compress`,
+    # `#decompress` and `#compress?`. The first takes a string and returns
+    # a compressed string, the second does the reverse and the third is a way
+    # for the compressor to advice the codec whether or not it's meaningful to
+    # encode the frame at all. `#compress?` will get the same argument as
+    # `#compress` and should return true or false. It could for example return
+    # true when the frame size is over a threshold value.
+    #
     # If you want to control how messages are framed you can implement your
     # own codec from scratch by implementing {#encode} and {#decode}, but most
     # of the time you should only need to implement {#encode_message} and
@@ -15,48 +26,90 @@ module Ione
     #
     # Codecs must be stateless.
     #
+    # Since the IO layer has no knowledge about the framing it can't know
+    # how many bytes are needed before a frame can be fully decoded so instead
+    # the codec needs to be able to process partial frames. At the same time
+    # a codec can be used concurrently and must be stateless. To support partial
+    # decoding a codec can return a state instead of a decoded message until
+    # a complete frame can be decoded.
+    #
+    # The codec must return three values: the last value must be true if a
+    # if a message was decoded fully, and false if not enough bytes were
+    # available. When it is true the first piece is the message and the second
+    # the channel. When it is false the first piece is the partial decoded
+    # state (this can be any object at all) and the second is nil. The partial
+    # decoded state will be passed in as the second argument on the next call.
+    #
+    # In other words: the first time {#decode} is called the second argument
+    # will be nil, but on subsequent calls, until the third return value is
+    # true, the second argument will be whatever was returned by the previous
+    # call.
+    #
+    # The buffer might contain more bytes than needed to decode a frame, and
+    # the implementation must not consume these. The implementation must
+    # consume all of the bytes of the current frame, but none of the bytes of
+    # the next frame.
+    #
     # Codecs must also make sure that these (conceptual) invariants hold:
     # `decode(encode(message, channel)) == [message, channel]` and
     # `encode(decode(frame)) == frame` (the return values are not entirely
     # compatible, but the concept should be clear).
     class Codec
+      # @param [Hash] options
+      # @option options [Object] :compressor a compressor to use to compress
+      #   and decompress frames (see above for the required interface it needs
+      #   to implement).
+      # @option options [Object] :lazy whether or not to decode the frames
+      #   immediately or return an object that can be decoded later, see {#decode}.
+      def initialize(options={})
+        @compressor = options[:compressor]
+        @lazy = options[:lazy]
+      end
+
       # Encodes a frame with a header that includes the frame size and channel,
       # and the message as body.
       #
+      # Will compress the frame body and set the compression flag when the codec
+      # has been configured with a compressor, and it says the frame should be
+      # compressed.
+      #
       # @param [Object] message the message to encode
       # @param [Integer] channel the channel to encode into the frame
       # @return [String] an encoded frame with the message and channel
       def encode(message, channel)
         data = encode_message(message)
-        [2, 0, channel, data.bytesize, data.to_s].pack(FRAME_V2_FORMAT)
+        flags = 0
+        if @compressor && @compressor.compress?(data)
+          data = @compressor.compress(data)
+          flags |= COMPRESSION_FLAG
+        end
+        [2, flags, channel, data.bytesize, data.to_s].pack(FRAME_V2_FORMAT)
       end
 
       # Decodes a frame, piece by piece if necessary.
       #
-      # Since the IO layer has no knowledge about the framing it can't know
-      # how many bytes are needed before a frame can be fully decoded so instead
-      # the codec needs to be able to process partial frames. At the same time
-      # a codec can be used concurrently and must be stateless. To support partial
-      # decoding a codec can return a state instead of a decoded message until
-      # a complete frame can be decoded.
-      #
-      # The codec must return three values: the last value must be true if a
-      # if a message was decoded fully, and false if not enough bytes were
-      # available. When it is true the first piece is the message and the second
-      # the channel. When it is false the first piece is the partial decoded
-      # state (this can be any object at all) and the second is nil. The partial
-      # decoded state will be passed in as the second argument on the next call.
+      # Since the codec can be called before a full frame has been received it
+      # returns a three-tuple where the last component is a boolean flag that says
+      # whether or not the frame is completely decoded. As long as the buffer
+      # does not contain a full frame the first component will be a state object
+      # which must be passed in as the second argument on the next call to
+      # {#decode}. When the buffer contains a full frame {#decode_message} will
+      # be called and the decoded message returned as the first component, the
+      # second will be the channel and the third will be true.
       #
-      # In other words: the first time {#decode} is called the second argument
-      # will be nil, but on subsequent calls, until the third return value is
-      # true, the second argument will be whatever was returned by the previous
-      # call.
+      # When the compression flag is set the codec uses the configured compressor
+      # to decode the frame before passing the decompressed bytes to
+      # {#decode_message}.
       #
-      # The buffer might contain more bytes than needed to decode a frame, and
-      # the implementation must not consume these. The implementation must
-      # consume all of the bytes of the current frame, but none of the bytes of
-      # the next frame.
+      # Since the IO thread can spend a significant proportion of its time doing
+      # frame decoding (the encoding is done in the calling thread) there is an
+      # option to create "lazy" codecs that return an intermediate object instead
+      # of a decoded message. When the codec is created with the `:lazy` option
+      # {#decode} returns an object with a `#decode` method, that in turn returns
+      # the decoded message.
       #
+      # @raise [Ione::Rpc::CodecError] when a frame has the compression flag set
+      #   and the codec is not configured with a compressor.
       # @param [Ione::ByteBuffer] buffer the byte buffer that contains the frame
       #   data. The byte buffer is owned by the caller and should only be read from.
       # @param [Object, nil] state the first value returned from the previous
@@ -73,12 +126,31 @@ module Ione
           state.read_header
         end
         if state.body_ready?
-          return decode_message(state.read_body), state.channel, true
+          body = state.read_body
+          channel = state.channel
+          if @lazy
+            message = LazilyDecodedFrame.new(self, state, body)
+          else
+            message = decode_body(state, body)
+          end
+          return message, state.channel, true
         else
           return state, nil, false
         end
       end
 
+      # @private
+      def decode_body(state, body)
+        if state.compressed?
+          if @compressor
+            body = @compressor.decompress(body)
+          else
+            raise CodecError, 'Compressed frame received but no compressor available'
+          end
+        end
+        decode_message(body)
+      end
+
       # Whether or not this codec supports channel recoding, see {#recode}.
       def recoding?
         true
@@ -127,6 +199,7 @@ module Ione
         def read_header
           n = @buffer.read_short
           @version = n >> 8
+          @compressed = n & COMPRESSION_FLAG == COMPRESSION_FLAG
           if @version == 1
             @channel = n & 0xff
           else
@@ -146,6 +219,23 @@ module Ione
         def body_ready?
           @length && @buffer.size >= @length
         end
+
+        def compressed?
+          @compressed
+        end
+      end
+
+      # @private
+      class LazilyDecodedFrame
+        def initialize(codec, state, body)
+          @codec = codec
+          @state = state
+          @body = body
+        end
+
+        def decode
+          @decoded ||= @codec.decode_body(@state, @body)
+        end
       end
 
       private
@@ -153,6 +243,7 @@ module Ione
       FRAME_V1_FORMAT = 'ccNa*'.freeze
       FRAME_V2_FORMAT = 'ccnNa*'.freeze
       CHANNEL_FORMAT = 'n'.freeze
+      COMPRESSION_FLAG = 1
     end
 
     # A codec that works with encoders like JSON, MessagePack, YAML and others

data/lib/ione/rpc/version.rb

@@ -2,6 +2,6 @@
 
 module Ione
   module Rpc
-    VERSION = '1.0.0.pre2'.freeze
+    VERSION = '1.0.0.pre3'.freeze
   end
 end

data/spec/ione/rpc/client_peer_spec.rb

@@ -138,6 +138,58 @@ module Ione
           end
         end
       end
+
+      describe '#stats' do
+        context 'returns a hash that' do
+          it 'contains the host' do
+            peer.stats.should include(host: connection.host)
+          end
+
+          it 'contains the port' do
+            peer.stats.should include(port: connection.port)
+          end
+
+          it 'contains the max number of channels' do
+            peer.stats.should include(max_channels: max_channels)
+          end
+
+          it 'contains the number of active channels' do
+            peer.stats.should include(active_channels: 0)
+            peer.send_message('hello')
+            peer.stats.should include(active_channels: 1)
+          end
+
+          it 'contains the number of queued messages' do
+            peer.stats.should include(queued_messages: 0)
+            17.times { peer.send_message('hello') }
+            peer.stats.should include(queued_messages: 1)
+            connection.data_listener.call('bar@000')
+            peer.stats.should include(queued_messages: 0)
+          end
+
+          it 'contains the number of sent messages' do
+            peer.stats.should include(sent_messages: 0)
+            17.times { peer.send_message('hello') }
+            connection.data_listener.call('bar@000')
+            peer.stats.should include(sent_messages: 17)
+          end
+
+          it 'contains the number of received responses' do
+            peer.stats.should include(received_responses: 0)
+            17.times { peer.send_message('hello') }
+            connection.data_listener.call('bar@000')
+            connection.data_listener.call('bar@000')
+            peer.stats.should include(received_responses: 2)
+          end
+
+          it 'contains the number of timed out responses' do
+            peer.stats.should include(timeouts: 0)
+            peer.send_message('hello', 1)
+            scheduler.timer_promises.first.fulfill
+            peer.stats.should include(timeouts: 1)
+          end
+        end
+      end
     end
   end
 end

data/spec/ione/rpc/client_spec.rb

@@ -419,6 +419,19 @@ module Ione
         end
       end
 
+      describe '#connection_stats' do
+        it 'is empty when no connections are open' do
+          client.connection_stats.should be_empty
+        end
+
+        it 'returns an array of the host, port and statistics from each open connection' do
+          client.start.value
+          stats = client.connection_stats
+          stats.should have(3).items
+          stats.should include(host: 'node1.example.com', port: 5432, fake_stats: true)
+        end
+      end
+
       context 'when disconnected' do
         it 'logs that the connection closed' do
           client.start.value
@@ -605,6 +618,14 @@ module ClientSpec
       @requests = []
     end
 
+    def stats
+      {
+        :host => @peer_connection.host,
+        :port => @peer_connection.port,
+        :fake_stats => true,
+      }
+    end
+
     def closed?
       !!@closed
     end

data/spec/ione/rpc/codec_spec.rb

@@ -34,6 +34,37 @@ module Ione
         it 'encodes the object as JSON' do
           encoded_message[8..-1].should == '{"foo":"bar","baz":42}'
         end
+
+        context 'with a compressor' do
+          let :codec do
+            CodecSpec::JsonCodec.new(compressor: compressor)
+          end
+
+          let :compressor do
+            double(:compressor)
+          end
+
+          before do
+            compressor.stub(:compress?).and_return(true)
+            compressor.stub(:compress).and_return('FAKECOMPRESSEDFREAME')
+          end
+
+          it 'sets the compression flag' do
+            encoded_message = codec.encode(object, 42)
+            encoded_message[1].unpack('c').should == [1]
+          end
+
+          it 'compresses the frame body' do
+            encoded_message = codec.encode(object, 42)
+            encoded_message[4, 4].unpack('N').should == [20]
+            encoded_message[8..-1].should == 'FAKECOMPRESSEDFREAME'
+          end
+
+          it 'does not compress the frame body when the compressor advices against it' do
+            compressor.stub(:compress?).and_return(false)
+            encoded_message[8..-1].should == '{"foo":"bar","baz":42}'
+          end
+        end
       end
 
       describe '#decode' do
@@ -88,6 +119,50 @@ module Ione
           message.should == object
           channel.should == 42
         end
+
+        context 'when the frame is compressed' do
+          let :codec do
+            CodecSpec::JsonCodec.new(compressor: compressor)
+          end
+
+          let :compressor do
+            double(:compressor)
+          end
+
+          let :encoded_message do
+            %(\x02\x01\x00\x2a\x00\x00\x00\x13FAKECOMPRESSEDFRAME)
+          end
+
+          before do
+            compressor.stub(:decompress).with('FAKECOMPRESSEDFRAME').and_return('{"foo":"bar","baz":42}')
+          end
+
+          it 'decompresses the frame before decoding it' do
+            message, channel, complete = codec.decode(Ione::ByteBuffer.new(encoded_message), nil)
+            complete.should be_true
+            message.should == object
+            channel.should == 42
+          end
+
+          it 'raises an error when the frame is compressed and the codec has not been configured with a compressor' do
+            codec = CodecSpec::JsonCodec.new
+            buffer = Ione::ByteBuffer.new(encoded_message)
+            expect { codec.decode(buffer, nil) }.to raise_error(CodecError, 'Compressed frame received but no compressor available')
+          end
+        end
+
+        context 'when the codec is lazy' do
+          let :codec do
+            CodecSpec::JsonCodec.new(lazy: true)
+          end
+
+          it 'returns an object with a #decode method instead of the message' do
+            message, channel, complete = codec.decode(Ione::ByteBuffer.new(encoded_message), nil)
+            complete.should be_true
+            channel.should == 42
+            message.decode.should == object
+          end
+        end
       end
 
       describe '#recode' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ione-rpc
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre2
+  version: 1.0.0.pre3
 platform: ruby
 authors:
 - Theo Hultberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-10 00:00:00.000000000 Z
+date: 2014-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ione