arpie 0.0.1

data/COPYING

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,89 @@
+= What's this?
+
+Arpie is a end-to-end framework for sending synchronous message-and-answer
+pairs, and serves as the basis for a RPC framework, handling a variety of protocols,
+including a generic Marshal proof of concept; writing your own Protocol is quite simple.
+
+* It uses ruby threads on the server side, one per connection.
+* The client is single-threaded.
+
+== 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.
+
+
+== Simple, contrived example: A string reverse server
+
+  require 'rubygems'
+  require 'arpie'
+  require 'socket'
+
+  server = TCPServer.new(51210)
+
+  e = Arpie::Endpoint.new(Arpie::MarshalProtocol.new)
+
+  e.handle do |ep, msg|
+    msg.reverse
+  end
+
+  e.accept do
+    server.accept
+  end
+
+  c = Arpie::Transport.new(Arpie::MarshalProtocol.new)
+  c.connect do |transport|
+    TCPSocket.new("127.0.0.1", 51210)
+  end
+
+  puts c.request "hi"
+  # => "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::ProxyEndpoint.new(Arpie::MarshalProtocol.new)
+
+  e.handle MyHandler.new
+
+  e.accept do
+    server.accept
+  end
+
+  c = Arpie::Transport.new(Arpie::MarshalProtocol.new)
+  c.connect do |transport|
+    TCPSocket.new("127.0.0.1", 51210)
+  end
+  p = Arpie::Proxy.new(c)
+
+  puts p.reverse "hi"
+  # => "ih"
+
+== 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.000167)
+  1000  0.120000   0.010000   0.130000 (  0.121834)
+
+  ruby xmlrpc/server - too slow to benchmark
+
+  Arpie: proxied MarshalProtocol
+     1  0.000000   0.000000   0.000000 (  0.000617)
+  1000  0.100000   0.020000   0.120000 (  0.114573)

data/Rakefile

@@ -0,0 +1,111 @@
+require "rake"
+require "rake/clean"
+require "rake/gempackagetask"
+require "rake/rdoctask"
+require "fileutils"
+include FileUtils
+
+##############################################################################
+# Configuration
+##############################################################################
+NAME = "arpie"
+VERS = "0.0.1"
+CLEAN.include ["**/.*.sw?", "pkg", ".config", "rdoc", "coverage"]
+RDOC_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', \
+  "#{NAME}: A high-performing layered RPC framework. Simple to use, simple to extend.", \
+  '--main', 'README']
+
+DOCS = ["README", "COPYING"]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add DOCS + ["doc/*.rdoc", "lib/**/*.rb"]
+end
+
+desc "Packages up #{NAME}"
+task :package => [:clean]
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.rubyforge_project = "#{NAME}"
+  s.version = VERS
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = DOCS + Dir["doc/*.rdoc"]
+  s.rdoc_options += RDOC_OPTS + ["--exclude", "^(examples|extras)\/"]
+  s.summary = "a synchronous RPC library based on google protobuf"
+  s.description = s.summary
+  s.author = "Bernhard Stoeckner"
+  s.email = "elven@swordcoast.net"
+  s.homepage = "http://#{NAME}.elv.es"
+  s.executables = []
+  s.required_ruby_version = ">= 1.8.4"
+  s.files = %w(COPYING README Rakefile) + Dir.glob("{bin,doc,spec,lib,tools,scripts,data}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_tar = true
+  p.gem_spec = spec
+end
+
+desc "Install #{NAME} gem"
+task :install do
+  sh %{rake package}
+  sh %{sudo gem1.8 install pkg/#{NAME}-#{VERS}}
+end
+
+desc "Regenerate proto classes"
+task :protoc do
+  sh %{rprotoc --out=lib/arpie arpie.proto}
+end
+
+desc "Install #{NAME} gem without docs"
+task :install_no_docs do
+  sh %{rake package}
+  sh %{sudo gem1.8 install pkg/#{NAME}-#{VERS} --no-rdoc --no-ri}
+end
+
+desc "Uninstall #{NAME} gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem1.8 uninstall #{NAME}}
+end
+
+desc "Upload #{NAME} gem to rubyforge"
+task :release => [:package] do
+  sh %{rubyforge login}
+  sh %{rubyforge add_release #{NAME} #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.tgz}
+  sh %{rubyforge add_file #{NAME} #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.gem}
+end
+
+require "spec/rake/spectask"
+
+desc "Run specs with coverage"
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_files = FileList["spec/*_spec.rb"]
+  t.spec_opts  = File.read("spec/spec.opts").split("\n")
+  t.rcov_opts  = File.read("spec/rcov.opts").split("\n")
+  t.rcov = true
+end
+
+desc "Run specs without coverage"
+task :default => [:spec_no_cov]
+Spec::Rake::SpecTask.new("spec_no_cov") do |t|
+  t.spec_files = FileList["spec/*_spec.rb"]
+  t.spec_opts  = File.read("spec/spec.opts").split("\n")
+end
+
+desc "Run rcov only"
+Spec::Rake::SpecTask.new("rcov") do |t|
+  t.rcov_opts  = File.read("spec/rcov.opts").split("\n")
+  t.spec_opts  = File.read("spec/spec.opts").split("\n")
+  t.spec_files = FileList["spec/*_spec.rb"]
+  t.rcov = true
+end
+
+desc "check documentation coverage"
+task :dcov do
+  sh "find lib -name '*.rb' | xargs dcov"
+end

data/lib/arpie.rb

@@ -0,0 +1,4 @@
+require 'arpie/protocol'
+require 'arpie/transport'
+require 'arpie/endpoint'
+require 'arpie/proxy'

data/lib/arpie/endpoint.rb

@@ -0,0 +1,94 @@
+module Arpie
+
+  # A Endpoint is the server-side part of a RPC setup.
+  # It accepts connections (via the acceptor), and handles
+  # incoming RPC calls on them.
+  #
+  # There will be one Thread per connection, so order of
+  # execution with multiple threads is not guaranteed.
+  class Endpoint
+
+    # Create a new Endpoint with the given +Protocol+.
+    # You will need to define a handler, and an acceptor
+    # before the endpoint becomes operational.
+    def initialize protocol
+      @protocol = protocol
+      @clients = []
+
+      @handler = lambda {|endpoint, message| raise ArgumentError, "No handler defined." }
+    end
+
+    # Provide an acceptor; this will be run in a a loop
+    # to get IO objects.
+    #
+    # Example:
+    #  listener = TCPServer.new(12345)
+    #  my_endpoint.accept do
+    #    listener.accept
+    #  end
+    def accept &acceptor
+      @acceptor = acceptor
+      Thread.new { _acceptor_thread }
+    end
+
+    # Set a message handler, which is a proc that will receive
+    # two parameters: the endpoint, and the message.
+    # Its return value will be sent as the reply.
+    #
+    # Example:
+    #  my_endpoint.handle do |endpoint, message|
+    #    puts "Got a message: #{message.inspect}"
+    #    "ok"
+    #  end
+    def handle &handler
+      raise ArgumentError, "need a block" unless block_given?
+      @handler = handler
+    end
+
+    private
+
+    def _handle message
+      @handler.call(self, message)
+    end
+
+    def _acceptor_thread
+      loop do
+        client = @acceptor.call(self)
+        @clients << client
+        Thread.new { _read_thread(client) }
+      end
+    end
+
+    def _read_thread client
+      loop do
+        break if client.eof?
+
+        message, answer = nil, nil
+        begin
+          message = @protocol.read_message(client)
+        rescue => e
+          $stderr.puts "client went away while reading the message: #{e.to_s}"
+          break
+        end
+
+        begin
+          answer = _handle(message)
+        rescue Exception => e
+          $stderr.puts "Error in handler: #{e.message.to_s}"
+          $stderr.puts e.backtrace.join("\n")
+          $stderr.puts "Returning exception for this call."
+          answer = e
+        end
+
+        begin
+          @protocol.write_message(client, answer)
+        rescue => e
+          puts "client went away while writing the answer:: #{e.to_s}"
+          break
+        end
+      end
+
+      @clients.delete(client)
+    end
+  end
+end

data/lib/arpie/protocol.rb

@@ -0,0 +1,51 @@
+module Arpie
+
+  # A Protocol converts messages (which are arbitary objects)
+  # to a suitable on-the-wire format, and back.
+  class Protocol
+    private_class_method :new
+
+    # Read a message from +io+. Block until a message
+    # has been received.
+    def read_message io
+    end
+
+    # Write a message to +io+.
+    def write_message io, message
+    end
+  end
+
+  # A sample binary protocol, upon which others can expand.
+  # The on the wire format is simply the data, prefixed
+  # with data.size.
+  class SizedProtocol < Protocol
+    def initialize
+      @max_message_size = 1024 * 1024
+    end
+
+    def read_message io
+      sz = io.read(8)
+      expect = sz.unpack("Q")[0]
+      data = io.read(expect)
+    end
+
+    def write_message io, message
+      io.write([message.size, message].pack("Qa*"))
+    end
+  end
+
+  # A procotol that simply Marshals all data sent over
+  # this protocol. Served as an example, but a viable
+  # choice for ruby-only production code.
+  class MarshalProtocol < SizedProtocol
+    public_class_method :new
+
+    def read_message io
+      Marshal.load super(io)
+    end
+
+    def write_message io, message
+      super io, Marshal.dump(message)
+    end
+  end
+end

data/lib/arpie/proxy.rb

@@ -0,0 +1,46 @@
+module Arpie
+
+  # The RPC call encapsulation used by ProxyEndpoint and Proxy.
+  class ProxyCall < Struct.new(:method, :argv); end
+
+  # 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 ProxyEndpoint < Endpoint
+    def handle handler
+      @handler = handler
+      @interface = @handler.class.public_instance_methods(false)
+    end
+
+    private
+
+    def _handle message
+      @interface.index(message.method.to_s) or raise NoMethodError,
+        "Unknown method."
+      @handler.send(message.method, *message.argv)
+    end
+  end
+
+  # A Proxy is a wrapper around a transport, which transparently tunnels
+  # method calls to the remote ProxyEndpoint.
+  class Proxy
+
+    # Create a new Proxy.
+    def initialize transport
+      @transport = transport
+    end
+
+    def method_missing method, *argv # :nodoc:
+      call = ProxyCall.new(method, argv)
+      ret = @transport.request(call)
+      case ret
+        when Exception
+          raise ret
+        else
+          ret
+      end
+    end
+  end
+end

data/lib/arpie/transport.rb

@@ -0,0 +1,37 @@
+module Arpie
+
+  # A Transport is a connection manager, and acts as the
+  # glue between a user-defined medium (for example, a TCP
+  # socket), and a protocol.
+  #
+  # See README for examples.
+  class Transport
+    attr_reader :protocol
+
+    def initialize protocol
+      @protocol = protocol
+      @io = nil
+    end
+
+    # Provide a connector block, which will be called
+    # each time a connection is needed.
+    # 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
+    end
+
+    # Send a message and receive a reply.
+    def request message
+      _connect
+      @protocol.write_message(@io, message)
+      @protocol.read_message(@io)
+    end
+
+    private
+    def _connect
+      @io ||= @connector.call(self)
+    end
+  end
+end

data/tools/benchmark.rb

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'socket'
+require 'arpie'
+require 'benchmark'
+require 'drb'
+require 'xmlrpc/server'
+require 'xmlrpc/client'
+
+class Wrap
+  def reverse x
+    x.reverse
+  end
+end
+
+include Arpie
+
+server = TCPServer.new(51210)
+
+endpoint = ProxyEndpoint.new MarshalProtocol.new
+endpoint.handle Wrap.new
+
+endpoint.accept do
+  server.accept
+end
+
+$transport = Transport.new MarshalProtocol.new
+$transport.connect(false) do |transport|
+  TCPSocket.new("127.0.0.1", 51210)
+end
+$proxy = Proxy.new $transport
+
+Benchmark.bm {|b|
+
+  puts ""
+  puts "native DRb"
+  drbserver = DRb.start_service nil, Wrap.new
+  drbobject = DRbObject.new nil, DRb.uri
+
+  b.report("   1") { 1.times { drbobject.reverse "benchmark" } }
+  b.report("1000") { 1000.times { drbobject.reverse "benchmark" } }
+
+  puts ""
+  puts "ruby xmlrpc/server - too slow to benchmark"
+  #server = XMLRPC::Server.new(51211, "127.0.0.1", 4, nil, false)
+  #server.add_handler(XMLRPC::iPIMethods("wrap"), Wrap.new)
+  #server_thread = Thread.new { server.serve }
+  #client = XMLRPC::Client.new( "127.0.0.1", "/", 51211)
+  #b.report("   1") {    1.times { client.call("wrap.reverse", "benchmark") } }
+  #b.report("1000") { 1000.times { client.call("wrap.reverse", "benchmark") } }
+  #server.shutdown
+  #server_thread.join
+
+  puts ""
+  puts "Arpie: proxied MarshalProtocol"
+  b.report("   1") {    1.times { $proxy.reverse "benchmark" } }
+  b.report("1000") { 1000.times { $proxy.reverse "benchmark" } }
+}

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: arpie
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Bernhard Stoeckner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-18 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: a synchronous RPC library based on google protobuf
+email: elven@swordcoast.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- COPYING
+files: 
+- COPYING
+- README
+- Rakefile
+- spec/spec.opts
+- spec/rcov.opts
+- lib/arpie.rb
+- lib/arpie
+- lib/arpie/protocol.rb
+- lib/arpie/transport.rb
+- lib/arpie/endpoint.rb
+- lib/arpie/proxy.rb
+- tools/benchmark.rb
+has_rdoc: true
+homepage: http://arpie.elv.es
+post_install_message: 
+rdoc_options: 
+- --quiet
+- --line-numbers
+- --inline-source
+- --title
+- "arpie: A high-performing layered RPC framework. Simple to use, simple to extend."
+- --main
+- README
+- --exclude
+- ^(examples|extras)/
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.4
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: arpie
+rubygems_version: 1.3.0
+signing_key: 
+specification_version: 2
+summary: a synchronous RPC library based on google protobuf
+test_files: []
+