arpie 0.0.6 → 0.1.0

data/COPYING

@@ -1,15 +0,0 @@
-Copyright (C) 2008 Bernhard Stoeckner <elven@swordcoast.net> and contributors
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along
-with this program; if not, write to the Free Software Foundation, Inc.,
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

data/README

@@ -1,167 +0,0 @@
-= What's this?
-
-Arpie is a end-to-end framework for sending protocol-encoded messages over arbitary
-IO channels, including UNIX/TCP Sockets, Pipes, and pidgeon carriers (depending on
-your implementation details).
-
-Arpie also provides a robust replay-protected RPC framework.
-
-The useful core of arpie is a protocol stack that can be used to read/split/assemble/write
-any data stream, but is tailored for packeted streaming data.
-
-The Arpie server uses one ruby-thread per client, the client runs entirely in the
-calling thread; though an example implementation for evented callbacks is provided.
-
-== Source Code
-
-Source code is in git[http://git.swordcoast.net/?p=lib/ruby/arpie.git;a=summary].
-
-You can contact me via email at elven@swordcoast.net.
-
-arpie is available on the rubygems gem server - just do <tt>gem1.8 install arpie</tt>
-to get the newest version.
-
-
-== Simple, contrived example: A string reverse server
-
-  require 'rubygems'
-  require 'arpie'
-  require 'socket'
-
-  server = TCPServer.new(51210)
-
-  e = Arpie::Server.new(Arpie::MarshalProtocol.new, Arpie::SizedProtocol.new)
-
-  e.handle do |server, ep, msg|
-    ep.write_message msg.reverse
-  end
-
-  e.accept do
-    server.accept
-  end
-
-  c = Arpie::Client.new(Arpie::MarshalProtocol.new, Arpie::SizedProtocol.new)
-  c.connect do
-    TCPSocket.new("127.0.0.1", 51210)
-  end
-
-  c.write_message "hi"
-  puts c.read_message
-  # => "ih"
-
-== Advanced, but still simple example: Using Proxy to access remote objects
-
-  require 'rubygems'
-  require 'arpie'
-  require 'socket'
-
-  class MyHandler
-    def reverse str
-      str.reverse
-    end
-  end
-
-  server = TCPServer.new(51210)
-
-  e = Arpie::ProxyServer.new(Arpie::MarshalProtocol.new, Arpie::SizedProtocol.new)
-
-  e.handle MyHandler.new
-
-  e.accept do
-    server.accept
-  end
-
-  p = Arpie::ProxyClient.new(Arpie::MarshalProtocol.new, Arpie::SizedProtocol.new)
-  p.connect do |transport|
-    TCPSocket.new("127.0.0.1", 51210)
-  end
-
-  puts p.reverse "hi"
-  # => "ih"
-
-== Writing custom Protocols
-
-You can use arpies Protocol layer to write your custom protocol parser/emitters.
-Consider the following, again very contrived, example. You have a linebased wire format,
-which sends regular object updates in multiple lines, each holding a property to be updated.
-What objects get updated is not relevant to this example.
-
-For this example, we'll be using the SeparatorProtocol already contained in protocols.rb as
-a base.
-
-  class AssembleExample < Arpie::Protocol
-
-    def from binary
-      # The wire format is simply a collection of lines
-      # where the first one is a number containing the
-      # # of lines to expect.
-      assemble! binary do |binaries, meta|
-        binaries.size >= 1 or incomplete!
-        binaries.size - 1 >= binaries[0].to_i or incomplete!
-
-        # Here, you can wrap all collected updates in
-        # whatever format you want it to be. We're just
-        # "joining" them to be a single array.
-        binaries.shift
-        binaries
-      end
-    end
-
-    def to object
-      yield object.size
-      object.each {|oo|
-        yield oo
-      }
-    end
-  end
-
-  p = Arpie::ProtocolChain.new(
-        AssembleExample.new,
-        Arpie::SeparatorProtocol.new
-      )
-  r, w = IO.pipe
-
-  p.write_message(w, %w{we want to be assembled})
-
-  p p.read_message(r)
-  # => ["we", "want", "to", "be", "assembled"]
-
-== Replay protection
-
-It can happen that a Client loses connection to a Server.
-In that case, the Transport tries transparently reconnecting by simply
-invoking the block again that was given to Client#connect.
-See the Client accessors for modifying this behaviour.
-
-It is assumed that each call, that is being placed, is atomic - eg, no
-connection losses in between message send and receive; lost messages
-will be retransmitted. Some Protocol classes provide support for replay
-protection through in-band UUIDs; though it is not a requirement to implement it.
-If a UUID is provided in the data stream, the Protocol will not call
-the handler again for retransmissions, but instead reply with the old,
-already evaluated value.
-
-Not all protocols support UUIDs; those who do not offer no replay protection,
-and special care has to be taken elsewhere.
-
-All object-encoding protocols support UUIDs, including YAML and Marshal.
-XMLRPC does not.
-
-== Benchmarks
-
-There is a benchmark script included in the git repository (and in the gem
-under tools/). A sample output follows; your milage may vary.
-
-        user     system      total        real
-
-  native DRb
-     1  0.000000   0.000000   0.000000 (  0.000172)
-  1000  0.110000   0.010000   0.120000 (  0.119767)
-
-  Arpie: proxied MarshalProtocol with replay protection through uuidtools
-     1  0.000000   0.000000   0.010000 (  0.075373)
-  1000  0.530000   0.090000   0.600000 (  0.608665)
-
-  Arpie: proxied MarshalProtocol without replay protection
-     1  0.000000   0.000000   0.000000 (  0.000173)
-  1000  0.170000   0.020000   0.190000 (  0.194649)

data/lib/arpie/client.rb

@@ -1,195 +0,0 @@
-module Arpie
-
-  # A Client is a connection manager, and acts as the
-  # glue between a user-defined medium (for example, a TCP
-  # socket), and a protocol, with automatic reconnecting
-  # and fault handling.
-  #
-  # See README for examples.
-  class Client
-    # The protocol chain used.
-    attr_reader :protocol
-
-    # How often should this Client retry a connection.
-    # 0 for never, greater than 0 for that many attempts,
-    # nil for infinite (default).
-    # Values other than nil will raise network exceptions
-    # to the caller.
-    attr_accessor :connect_retry
-
-    # How long should the caller sleep after each reconnect
-    # attempt. (default: 1.0). The default value is probably
-    # okay. Do not set this to 0; that will produce
-    # unnecessary load in case of network failure.
-    attr_accessor :connect_sleep
-
-    def initialize *protocols
-      @protocol = Arpie::ProtocolChain.new(*protocols)
-      @read_io = nil
-      @write_io = nil
-      @connector = lambda { raise ArgumentError, "No connector specified, cannot connect to Endpoint." }
-      @connect_retry = nil
-      @connect_sleep = 1.0
-      @on_error = lambda {|client, exception|
-        $stderr.puts "Error in Transport IO: #{exception.message.to_s}"
-        $stderr.puts exception.backtrace.join("\n")
-        $stderr.puts "Set Transport#on_error &block to override this."
-      }
-    end
-
-    # Provide a connector block, which will be called
-    # each time a connection is needed.
-    # Expectes an IO object.
-    # Alternatively, you can return a two-item array.
-    # To test something without involving any networking,
-    # simply run IO.pipe in this block.
-    # Set +connect_immediately+ to true to connect
-    # immediately, instead on the first message.
-    def connect connect_immediately = false, &connector
-      @connector = connector
-      _connect if connect_immediately
-      self
-    end
-
-    # Set an error handler. It will be called with two
-    # parameters, the client, and the exception that occured.
-    # Optional, and just for notification.
-    def on_error &handler #:yields: client, exception
-      @on_error = handler
-      self
-    end
-
-    # Send a message. Returns immediately.
-    def write_message message
-      io_retry do
-        @protocol.write_message(@write_io, message)
-      end
-    end
-    alias_method :<<, :write_message
-
-    # Receive a message. Blocks until received.
-    def read_message
-      io_retry do
-        return @protocol.read_message(@read_io)
-      end
-    end
-
-    # Execute the given block until all connection attempts
-    # have been exceeded.
-    # Yields self.
-    # You do not usually want to use this.
-    def io_retry &block
-      try = 0
-
-      begin
-        _connect
-        yield self
-      rescue IOError => e
-        try += 1
-        @on_error.call(self, e) if @on_error
-        p e
-
-        if @connect_retry == 0 || (@connect_retry && try > @connect_retry)
-          raise EOFError, "Cannot read from io: lost connection after #{try} attempts (#{e.message.to_s})"
-        end
-
-        sleep @connect_sleep
-        begin; @read_io.close if @read_io; rescue; end
-        @read_io = nil
-        begin; @write_io.close if @write_io; rescue; end
-        @write_io = nil
-        retry
-      end
-    end
-
-  private
-
-    def _connect
-      @read_io and return
-      @read_io, @write_io = @connector.call(self)
-      @protocol.reset
-      @write_io ||= @read_io
-    end
-  end
-
-  # A simple pseudo event-based client, using a thread
-  # with a callback.
-  class EventedClient < Client
-    private :read_message
-
-    # Set a callback for incoming messages.
-    def handle &handler #:yields: client, message
-      @handler = handler
-    end
-
-  private
-
-    def _read_thread
-      loop do
-        io_retry do
-          message = read_message
-          @handler and @handler.call(self, message)
-        end
-      end
-    end
-
-    def _connect
-      super
-      @read_thread ||= Thread.new { _read_thread }
-    end
-  end
-
-
-  # A Client extension which provides a RPC-like
-  # interface. Used by ProxyClient.
-  class RPCClient < Client
-    private :read_message, :write_message
-
-    def initialize *protocols
-      super(*protocols)
-
-      @on_pre_call = lambda {|client, message| }
-      @on_post_call = lambda {|client, message, reply| }
-    end
-
-    # Callback that gets invoked before placing a call to the
-    # Server. You can stop the call from happening by raising
-    # an exception (which will be passed on to the caller).
-    def pre_call &handler #:yields: client, message
-      @on_pre_call = handler
-      self
-    end
-
-    # Callback that gets invoked after receiving an answer.
-    # You can raise an exception here; and it will be passed
-    # to the caller, instead of returning the value.
-    def post_call &handler #:yields: client, message, reply
-      @on_post_call = handler
-      self
-    end
-
-
-    # Send a message and receive a reply in a synchronous
-    # fashion. Will block until transmitted, or until
-    # all reconnect attempts failed.
-    def request message
-      reply = nil
-
-      @on_pre_call.call(self, message) if @on_pre_call
-
-      io_retry do
-        write_message(message)
-        reply = read_message
-      end
-
-      @on_post_call.call(self, message, reply) if @on_post_call
-
-      case reply
-        when Exception
-          raise reply
-        else
-          reply
-      end
-    end
-  end
-end

data/lib/arpie/proxy.rb

@@ -1,143 +0,0 @@
-require 'uuidtools'
-
-module Arpie
-
-  # A Endpoint which supports arbitary objects as handlers,
-  # instead of a proc.
-  #
-  # Note that this will only export public instance method
-  # of the class as they are defined.
-  class ProxyServer < Server
-
-    # An array containing symbols of method names that the
-    # handler should be allowed to call. Defaults to
-    # all public instance methods the class defines (wysiwyg).
-    # Set this to nil to allow calling of ALL methods, but be
-    # warned of the security implications (instance_eval, ..).
-    attr_accessor :interface
-
-    # Set this to false to disable replay protection.
-    attr_accessor :uuid_tracking
-
-    # The maximum number of method call results to remember.
-    # Defaults to 100, which should be enough for everyone. ;)
-    attr_accessor :max_uuids
-
-    def initialize *va
-      super
-      @uuids = {}
-      @max_uuids = 100
-      @uuid_tracking = true
-    end
-
-    # Set a class handler. All public instance methods will be
-    # callable over RPC (with a Proxy object) (see attribute interface).
-    def handle handler
-      @handler = handler
-      @interface = handler.class.public_instance_methods(false).map {|x|
-        x.to_sym
-      }
-      self
-    end
-
-    private
-
-    def _handle endpoint, message
-      if !@handler.respond_to?(message.meth.to_sym) ||
-          (@interface && !@interface.index(message.meth.to_sym))
-        endpoint.write_message NoMethodError.new("No such method: #{message.meth.inspect}")
-        return
-      end
-
-      begin
-        # Prune old serials. This can probably be optimized, but works well enough for now.
-        if @uuid_tracking && message.uuid
-          uuid, serial = * message.uuid
-
-          raise ArgumentError,
-            "Invalid UUID given, expect [uuid/64bit, serial/numeric]." unless
-              uuid.is_a?(Integer) && serial.is_a?(Integer)
-
-          # Limit to sane values.
-          uuid   &= 0xffffffffffffffff
-          serial &= 0xffffffffffffffff
-
-          timestamps = @uuids.values.map {|v| v[0] }.sort
-          latest_timestamp = timestamps[-@max_uuids]
-          @uuids.reject! {|uuid, (time, value)|
-            time < latest_timestamp
-          } if latest_timestamp
-
-          endpoint.write_message((@uuids[message.uuid] ||=
-            [Time.now, @handler.send(message.meth, *message.argv)])[1])
-
-        else
-          endpoint.write_message @handler.send(message.meth, *message.argv)
-        end
-      rescue IOError
-        raise
-
-      rescue Exception => e
-        endpoint.write_message RuntimeError.new("Internal Error")
-        raise
-      end
-    end
-  end
-
-  # A Proxy is a wrapper around a Client, which transparently tunnels
-  # method calls to the remote ProxyServer.
-  # Note that the methods of Client cannot be proxied.
-  class ProxyClient < RPCClient
-    attr_accessor :namespace
-
-    # Set to false to disable replay protection.
-    # Default is true.
-    attr_accessor :replay_protection
-
-    # The current serial for this transport.
-    attr_accessor :serial
-
-    # The generated uuid for this Client.
-    # nil if no call has been made yet.
-    attr_accessor :uuid
-
-    def initialize *protocols
-      super
-      @protocol, @namespace = protocol, ""
-      @serial = 0
-      @uuid_generator = lambda {|client, method, argv|
-        UUIDTools::UUID.random_create.to_i
-      }
-      @replay_protection = true
-    end
-
-    # Set up a new UUID generator for this proxy client.
-    # Make sure that this yields really random numbers.
-    # The default uses the uuidtools gem and is usually okay.
-    #
-    # This gets called exactly once for each created ProxyClient.
-    def uuid_generator &handler #:yields: client, method, argv
-      @uuid_generator = handler
-      self
-    end
-
-    def method_missing meth, *argv # :nodoc:
-      serial = nil
-      if @replay_protection
-        serial = [
-          @uuid ||= @uuid_generator.call(self, meth, argv),
-          @serial += 1
-        ]
-      end
-
-      call = Arpie::RPCall.new(@namespace, meth, argv, serial)
-      ret = self.request(call)
-      case ret
-        when Exception
-          raise ret
-        else
-          ret
-      end
-    end
-  end
-end