ione-rpc 1.0.0.pre0

data/lib/ione/rpc/codec.rb

@@ -0,0 +1,153 @@
+# encoding: utf-8
+
+module Ione
+  module Rpc
+    # 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.
+    #
+    # 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
+    # {#decode_message} which take care of encoding and decoding the message,
+    # and leave the framing to the default implementation. If you decide to
+    # implement {#encode} and {#decode} you don't need to subclass this class.
+    #
+    # Codecs must be stateless.
+    #
+    # 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
+      # Encodes a frame with a header that includes the frame size and channel,
+      # and the message as body.
+      #
+      # @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)
+        [1, channel, data.bytesize, data.to_s].pack('ccNa*')
+      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.
+      #
+      # 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.
+      #
+      # @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
+      #   call, unless the previous call resulted in a completely decoded frame,
+      #   in which case it is nil
+      # @return [Array<Object, Integer, Boolean>] three values where the last is
+      #   true when a frame could be completely decoded. When the last value is
+      #   true the first value is the decoded message and the second the channel,
+      #   but when the last value is false the first is the partial state (see
+      #   the `state` parameter) and the second is nil.
+      def decode(buffer, state)
+        state ||= State.new(buffer)
+        if state.header_ready?
+          state.read_header
+        end
+        if state.body_ready?
+          return decode_message(state.read_body), state.channel, true
+        else
+          return state, nil, false
+        end
+      end
+
+      # @!method encode_message(message)
+      #
+      # Encode an object to bytes that can be sent over the network.
+      #
+      # @param [Object] message the object to encode
+      # @return [String, Ione::ByteBuffer] an object that responds to `#to_s`
+      #   and `#bytesize`, for example a `String` or a `Ione::ByteBuffer`
+
+      # @!method decode_message(str)
+      #
+      # Decode a string of bytes to an object.
+      #
+      # @param [String] str an encoded message, the same string that was produced
+      #   by {#encode_message}
+      # @return [Object] the decoded message
+
+      # @private
+      class State
+        attr_reader :channel
+
+        def initialize(buffer)
+          @buffer = buffer
+        end
+
+        def read_header
+          n = @buffer.read_short
+          @version = n >> 8
+          @channel = n & 0xff
+          @length = @buffer.read_int
+        end
+
+        def read_body
+          @buffer.read(@length)
+        end
+
+        def header_ready?
+          @length.nil? && @buffer.size >= 6
+        end
+
+        def body_ready?
+          @length && @buffer.size >= @length
+        end
+      end
+    end
+
+    # A codec that works with encoders like JSON, MessagePack, YAML and others
+    # that follow the informal Ruby standard of having a `#dump` method that
+    # encodes and a `#load` method that decodes.
+    #
+    # @example A codec that encodes messages as JSON
+    #   codec = StandardCodec.new(JSON)
+    #
+    # @example A codec that encodes messages as MessagePack
+    #   codec = StandardCodec.new(MessagePack)
+    class StandardCodec < Codec
+      # @param [#load, #dump] delegate
+      def initialize(delegate)
+        @delegate = delegate
+      end
+
+      # Uses the delegate's `#dump` to encode the message
+      def encode_message(message)
+        @delegate.dump(message)
+      end
+
+      # Uses the delegate's `#load` to decode the message
+      def decode_message(str)
+        @delegate.load(str)
+      end
+    end
+  end
+end

data/lib/ione/rpc/peer.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Ione
+  module Rpc
+    # @private
+    class Peer
+      attr_reader :host, :port
+
+      def initialize(connection, codec)
+        @connection = connection
+        @connection.on_data(&method(:handle_data))
+        @connection.on_closed(&method(:handle_closed))
+        @host = @connection.host
+        @port = @connection.port
+        @codec = codec
+        @buffer = Ione::ByteBuffer.new
+        @closed_promise = Promise.new
+        @current_message = nil
+      end
+
+      def on_closed(&listener)
+        @closed_promise.future.on_value(&listener)
+      end
+
+      def close
+        @connection.close
+      end
+
+      protected
+
+      def handle_data(new_data)
+        @buffer << new_data
+        while true
+          @current_message, channel, complete = @codec.decode(@buffer, @current_message)
+          break unless complete
+          handle_message(@current_message, channel)
+          @current_message = nil
+        end
+      end
+
+      def handle_message(message, channel)
+      end
+
+      def handle_closed(cause=nil)
+        @closed_promise.fulfill(cause)
+      end
+
+      def write_message(message, channel)
+        @connection.write(@codec.encode(message, channel))
+      end
+    end
+  end
+end

data/lib/ione/rpc/server.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+module Ione
+  module Rpc
+    # This is the base class of server peers.
+    #
+    # To implement a server you need to create a subclass of this class and
+    # implement {#handle_request}. You can also optionally implement
+    # {#handle_connection} to do initialization when a new client connects.
+    class Server
+      attr_reader :port
+
+      def initialize(port, codec, options={})
+        @port = port
+        @codec = codec
+        @io_reactor = options[:io_reactor] || Io::IoReactor.new
+        @stop_reactor = !options[:io_reactor]
+        @queue_length = options[:queue_size] || 5
+        @bind_address = options[:bind_address] || '0.0.0.0'
+        @logger = options[:logger]
+      end
+
+      # Start listening for client connections. This also starts the IO reactor
+      # if it was not already started.
+      #
+      # The returned future resolves when the server is ready to accept
+      # connections, or fails if there is an error starting the server.
+      #
+      # @return [Ione::Future<Ione::Rpc::Server>] a future that resolves to the
+      #   server when all hosts have been connected to.
+      def start
+        @io_reactor.start.flat_map { setup_server }.map(self)
+      end
+
+      # Stop the server and close all connections. This also stops the IO reactor
+      # if it has not already stopped.
+      #
+      # @return [Ione::Future<Ione::Rpc::Server>] a future that resolves to the
+      #   server when all connections have closed and the IO reactor has stopped.
+      def stop
+        @io_reactor.stop.map(self)
+      end
+
+      protected
+
+      # Override this method to do work when a new client connects.
+      #
+      # This method may be called concurrently.
+      #
+      # @return [nil] the return value of this method is ignored
+      def handle_connection(connection)
+      end
+
+      # Override this method to handle requests.
+      #
+      # You must respond to all requests, otherwise the client will eventually
+      # use up all of its channels and not be able to send any more requests.
+      #
+      # This method may be called concurrently.
+      #
+      # @param [Object] message a (decoded) message from a client
+      # @param [#host, #port, #on_closed] connection the client connection that
+      #   received the message
+      # @return [Ione::Future<Object>] a future that will resolve to the response.
+      def handle_request(message, connection)
+        Future.resolved
+      end
+
+      private
+
+      def setup_server
+        @io_reactor.bind(@bind_address, @port, @queue_length) do |acceptor|
+          @logger.info('Server listening for connections on %s:%d' % [@bind_address, @port]) if @logger
+          acceptor.on_accept do |connection|
+            @logger.info('Connection from %s:%d accepted' % [connection.host, connection.port]) if @logger
+            peer = ServerPeer.new(connection, @codec, self)
+            peer.on_closed do
+              @logger.info('Connection from %s:%d closed' % [connection.host, connection.port]) if @logger
+            end
+            handle_connection(peer)
+          end
+        end
+      end
+
+      # @private
+      class ServerPeer < Peer
+        def initialize(connection, codec, server)
+          super(connection, codec)
+          @server = server
+        end
+
+        def handle_message(message, channel)
+          f = @server.handle_request(message, self)
+          f.on_value do |response|
+            write_message(response, channel)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ione/rpc/version.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+module Ione
+  module Rpc
+    VERSION = '1.0.0.pre0'.freeze
+  end
+end

data/lib/ione/rpc.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require 'ione'
+
+
+module Ione
+  module Rpc
+  end
+end
+
+require 'ione/rpc/peer'
+require 'ione/rpc/client_peer'
+require 'ione/rpc/server'
+require 'ione/rpc/client'
+require 'ione/rpc/codec'

data/spec/ione/rpc/client_peer_spec.rb

@@ -0,0 +1,109 @@
+# encoding: utf-8
+
+require 'spec_helper'
+require 'ione/rpc/peer_common'
+
+
+module Ione
+  module Rpc
+    describe ClientPeer do
+      let! :peer do
+        RpcSpec::TestClientPeer.new(connection, codec, max_channels)
+      end
+
+      let :connection do
+        RpcSpec::FakeConnection.new
+      end
+
+      let :codec do
+        double(:codec)
+      end
+
+      let :max_channels do
+        16
+      end
+
+      before do
+        codec.stub(:decode) do |buffer, current_frame|
+          message = buffer.to_s.scan(/[\w\d]+@\d+/).flatten.first
+          if message
+            payload, channel = message.split('@')
+            buffer.discard(message.bytesize)
+            [double(:complete, payload: payload), channel.to_i(10), true]
+          else
+            [double(:partial), nil, false]
+          end
+        end
+        codec.stub(:encode) do |message, channel|
+          '%s@%03d' % [message, channel]
+        end
+      end
+
+      include_examples 'peers'
+
+      context 'when the connection closes' do
+        it 'fails all outstanding requests when closing' do
+          f1 = peer.send_message('hello')
+          f2 = peer.send_message('world')
+          connection.closed_listener.call
+          expect { f1.value }.to raise_error(Io::ConnectionClosedError)
+          expect { f2.value }.to raise_error(Io::ConnectionClosedError)
+        end
+      end
+
+      describe '#send_message' do
+        it 'encodes and sends a request frame' do
+          peer.send_message('hello')
+          connection.written_bytes.should start_with('hello')
+        end
+
+        it 'uses the next available channel' do
+          peer.send_message('hello')
+          peer.send_message('foo')
+          connection.data_listener.call('world@0')
+          peer.send_message('bar')
+          connection.written_bytes.should == 'hello@000foo@001bar@000'
+        end
+
+        it 'queues requests when all channels are in use' do
+          (max_channels + 2).times { peer.send_message('foo') }
+          connection.written_bytes.bytesize.should == max_channels * 7
+        end
+
+        it 'sends queued requests when channels become available' do
+          (max_channels + 2).times { |i| peer.send_message("foo#{i.to_s.rjust(3, '0')}") }
+          length_before = connection.written_bytes.bytesize
+          connection.data_listener.call('bar@003')
+          connection.written_bytes[length_before, 10].should == "foo#{max_channels.to_s.rjust(3, '0')}@003"
+          connection.data_listener.call('bar@003')
+          connection.written_bytes[length_before + 10, 10].should == "foo#{(max_channels + 1).to_s.rjust(3, '0')}@003"
+        end
+
+        it 'returns a future that resolves to the response' do
+          f = peer.send_message('foo')
+          f.should_not be_resolved
+          connection.data_listener.call('bar@000')
+          f.value.payload.should == 'bar'
+        end
+      end
+    end
+  end
+end
+
+module RpcSpec
+  class TestClientPeer < Ione::Rpc::ClientPeer
+    attr_reader :messages
+
+    def initialize(*)
+      super
+      @messages = []
+    end
+
+    def handle_message(*pair)
+      @messages << pair
+      super
+    end
+
+    public :send_message
+  end
+end