jason-o-matic-drbfire 0.1.0

data/ChangeLog

@@ -0,0 +1,101 @@
+Wed Feb 25 20:56:11 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.1.0. Really.
+
+	* lib/drb/drbfire.rb: Updated the version number. Also added a few
+	  nodoc directives.
+
+Wed Feb 25 20:05:10 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.1.0.
+
+	* lib/drb/drbfire.rb: Simplified to only use one port.
+
+	* test/test_drbfire.rb: Removed obsolete tests related to the above
+	  change.
+
+	* lib/drb/drbfire.rb: Added id wrapping and one server per process
+	  caveats to the documentation.
+
+Sun Jan 18 22:24:10 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.0.7.
+
+	* lib/drb/drbfire.rb: forgot to require timeout.
+
+Sun Jan 18 22:09:51 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.0.6.
+
+Sun Jan 18 22:00:44 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* lib/drb/drbfire.rb: ignored connections with invalid client ids.
+
+	* *: added copyright notices.
+
+	* lib/drb/drbfire.rb: added RDoc.
+
+	* README: added.
+
+	* INSTALL: added.
+
+Sat Jan 17 13:03:27 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* lib/drb/drbfire.rb: increased robustness when accepting connections.
+
+	* lib/drb/drbfire.rb: fixed a race condition when accepting signal
+	  connections.
+
+	* test/test_drbfire.rb: use the packet format constant.
+
+	* lib/drb/drbfire.rb: added a VERSION constant.
+
+	* Release 0.0.5.
+
+Fri Jan 16 14:34:52 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.0.4.
+
+Fri Jan 16 14:30:13 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* test/test_drbfire.rb: improved the overall communication tests to
+	  include client-side callbacks.
+
+	* lib/drb/drbfire.rb: fixed a bug with client-side callbacks caused by
+	  improperly reporting the uri.
+
+	* samples/*.rb: improved the samples to include client-side callbacks.
+
+Fri Jan 16 11:32:40 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.0.3.
+
+Fri Jan 16 11:30:58 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* lib/drb/drbfire.rb: added debugging code.
+
+Fri Jan 16 11:11:02 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* samples/server.rb: improved argument handling and added the ability
+	  to specify the use of ssl.
+
+	* samples/client.rb: ditto.
+
+	* lib/drb/drbfire.rb: removed old debugging code.
+
+Fri Jan 16 10:41:53 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* samples/server.rb: added the ability to specify the host on the
+	  commandline.
+
+	* samples/client.rb: ditto.
+
+Thu Jan 15 21:01:02 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Release 0.0.2.
+
+Thu Jan 15 20:59:08 2004  Nathaniel Talbott  <nathaniel@talbott.ws>
+
+	* Changed how client id's are packed.
+
+vim: set noexpandtab

data/INSTALL

@@ -0,0 +1,10 @@
+From the root of the package, run:
+
+  ruby setup.rb config
+  ruby setup.rb setup
+  ruby setup.rb install
+
+Further install options are available using:
+
+  ruby setup.rb --help
+

data/README

@@ -0,0 +1,48 @@
+= DRbFire
+
+The DRb Firewall Protocol, or DRbFire, is a DRb protocol that allows 
+easy bidirectional communication in the presence of a firewall.
+
+
+== Usage
+
+DRbFire's usage is documented in the source using RDoc.
+
+
+== Installation
+
+See the INSTALL file.
+
+
+== History
+
+See the ChangeLog file.
+
+
+== Feedback
+
+Feedback of any kind is welcome; you can contact me (Nathaniel
+Talbott) at drbfire@talbott.ws.
+
+
+== More Information
+
+DRbFire's home is at http://rubyforge.org/projects/drbfire.
+
+
+== Copyright
+
+Copyright (c) 2004 Nathaniel Talbott. All Rights Reserved.
+
+
+== License
+
+DRbFire is free software distributed under the Ruby license. See the
+COPYING file in the standard Ruby distribution for details.
+
+
+== Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.

data/drbfire.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{drbfire}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nathaniel Talbott"]
+  s.date = %q{2009-02-07}
+#   s.default_executable = %q{deep_test}
+  s.description = %q{DRbFire allows easy bidirectional DRb communication in the presence of a firewall.}
+  s.email = %q{drbfire@talbott.ws}
+#   s.executables = ["deep_test"]
+  s.extra_rdoc_files = ["README", "ChangeLog"]
+  s.files = ["ChangeLog", "drbfire.gemspec", "INSTALL", "lib/drb/drbfire.rb", "README", "sample/client.rb", "sample/server.rb", "setup.rb", "test/test_drbfire.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://rubyforge.org/projects/drbfire}
+  s.rdoc_options = ["--title", "DRbFire", "--main", "README", "--line-numbers"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{drbfire}
+  s.rubygems_version = %q{1.3.0}
+  s.summary = %q{DRbFire allows easy bidirectional DRb communication in the presence of a firewall.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/drb/drbfire.rb

@@ -0,0 +1,289 @@
+# :include:README
+#--
+# Author:: Nathaniel Talbott.
+# Copyright:: Copyright (c) 2004 Nathaniel Talbott. All rights reserved.
+# License:: Ruby license.
+
+require 'delegate'
+require 'drb'
+require 'timeout'
+
+# = DRb Firewall Protocol
+# 
+# == Prerequisites
+#
+# It is assumed that you already know how to use DRb; if you don't
+# you'll need to go read up on it and understand the basics of how it
+# works before using DRbFire. DRbFire actually wraps the standard
+# protocols that DRb uses, so generally anything that applies to them
+# applies to DRbFire.
+#
+#
+# == Basic Usage
+# 
+# Using DRbFire is quite simple, and can be summed up in four steps:
+#
+# 1. Start with <tt>require 'drb/drbfire'</tt>.
+#
+# 2. Use <tt>drbfire://</tt> instead of <tt>druby://</tt> when
+#    specifying the server url.
+#
+# 3. When calling <tt>DRb.start_service</tt> on the client, specify
+#    the server's uri as the uri (as opposed to the normal usage, which
+#    is to specify *no* uri).
+#
+# 4. Specify the right configuration when calling
+#    <tt>DRb.start_service</tt>, specifically the role to use:
+#    On the server:: <tt>DRbFire::ROLE => DRbFire::SERVER</tt>
+#    On the client:: <tt>DRbFire::ROLE => DRbFire::CLIENT</tt>
+#
+# So a simple server would look like:
+#
+#   require 'drb/drbfire'
+#
+#   front = ['a', 'b', 'c']
+#   DRb.start_service('drbfire://some.server.com:5555', front, DRbFire::ROLE => DRbFire::SERVER)
+#   DRb.thread.join
+#
+# And a simple client:
+#
+#   require 'drb/drbfire'
+#
+#   DRb.start_service('drbfire://some.server.com:5555', nil, DRbFire::ROLE => DRbFire::CLIENT)
+#   DRbObject.new(nil, 'drbfire://some.server.com:5555').each do |e|
+#     p e
+#   end
+#
+# 
+# == Advanced Usage
+#
+# You can do some more interesting tricks with DRbFire, too:
+#
+# <b>Using SSL</b>:: To do this, you have to set the delegate in the
+#                    configuration (on both the server and the client) using
+#                    <tt>DRbFire::DELEGATE => DRb::DRbSSLSocket</tt>. Other
+#                    DRb protcols may also work as delegates, but only the
+#                    SSL protocol is tested.
+#
+#
+# == Caveats
+#
+# * DRbFire uses a 32-bit id space, meaning ids will wrap after
+#   approximately ~4.2 billion connections. If that's a non-theoretical
+#   problem for you, and you tell me about it, I'll figure out some
+#   way to fix it. It'd be worth it just to find out that DRbFire is
+#   being used in such a mind-blowing fashion.
+#
+# * You're limited to one _server_ per process at this point. You can
+#   have (and handle) as many clients as you want (well, ok, so I just
+#   said there's really a limit somewhere around 4.2 billion. I'm
+#   trying to simplify here). Again, this is possible to deal with,
+#   but not something that I've needed at this point and not something
+#   I'm guessing is terribly common. Let me know if it's a problem for
+#   you.
+
+
+module DRbFire
+  # The current version.
+  VERSION = [0, 1, 0]
+  
+  # The role configuration key.
+  ROLE = "#{self}::ROLE"
+
+  # The server role configuration value.
+  SERVER = "#{self}::SERVER"
+
+  # The client role configuration value.
+  CLIENT = "#{self}::CLIENT"
+
+  # The delegate configuration key.
+  DELEGATE = "#{self}::DELEGATE"
+
+  # Miscellaneous constants
+  SCHEME = "drbfire" #:nodoc:
+  ID_FORMAT = "N" #:nodoc:
+  INCOMING_CONN = "1" #:nodoc:
+  OUTGOING_CONN = "2" #:nodoc:
+  SIGNAL_CONN = "3" #:nodoc:
+
+  class Protocol < SimpleDelegator #nodoc:all
+    class ClientServer
+      attr_reader :signal_id
+
+      def initialize(uri, config)
+        @uri = uri
+        @config = config
+        @connection = Protocol.open(uri, config, SIGNAL_CONN)
+        @signal_id = @connection.read_signal_id
+      end
+
+      def uri
+        "#{@uri}?#{@signal_id}"
+      end
+
+      def accept
+        @connection.stream.read(1)
+        connection = Protocol.open(@uri, @config, OUTGOING_CONN)
+        connection.stream.write([@signal_id].pack(ID_FORMAT))
+        connection
+      end
+
+      def close
+        @connection.close
+      end
+    end
+
+    class ClientServerProxy
+      def initialize(connection, id)
+        @connection = connection
+        @id = id
+        @queue = Queue.new
+      end
+
+      def write_signal_id
+        @connection.stream.write([@id].pack(ID_FORMAT))
+      end
+
+      def push(connection)
+        @queue.push(connection)
+      end
+
+      def open
+        @connection.stream.write("0")
+        timeout(20) do
+          @queue.pop
+        end
+      rescue TimeoutError
+        raise DRb::DRbConnError, "Unable to get a client connection."
+      end
+    end
+
+    class << self
+      def open_server(uri, config)
+        if(server?(config))
+          @client_servers ||= {}
+          
+          sock = delegate(config).open_server(uri, config)
+          
+          # get the uri from the delegate, and replace the scheme with drbfire://
+          # this allows randomly chosen ports (:0) to work
+          scheme = sock.uri.match(/^(.*):\/\//)[1]
+          drbfire_uri = sock.uri.sub(scheme, SCHEME)
+          
+          new(drbfire_uri, sock)
+        else
+          ClientServer.new(uri, config)
+        end
+      end
+
+      def open(uri, config, type=INCOMING_CONN)
+        unless(server?(config))
+          connection = new(uri, delegate(config).open(uri, config))
+          connection.stream.write(type)
+          connection
+        else
+          @client_servers[parse_uri(uri).last.to_i].open
+        end
+      end
+
+      def add_client_connection(id, connection)
+        if((c = @client_servers[id]))
+          c.push(connection)
+        else
+        end
+      end
+
+      def add_client_server(id, server)
+        @client_servers[id] = server
+      end
+
+     def parse_uri(uri)
+        if(%r{^#{SCHEME}://([^:]+):(\d+)(?:\?(.+))?$} =~ uri)
+          [$1, $2.to_i, $3]
+        else
+          raise DRb::DRbBadScheme, uri unless(/^#{SCHEME}/ =~ uri)
+          raise DRb::DRbBadURI, "Can't parse uri: #{uri}"
+        end
+      end
+
+      def uri_option(uri, config)
+        host, port, option = parse_uri(uri)
+        return "#{SCHEME}://#{host}:#{port}", option
+      end
+
+      private
+
+      def server?(config)
+        raise "Invalid configuration" unless(config.include?(ROLE))
+        config[ROLE] == SERVER
+      end
+
+      def delegate(config)
+        unless(defined?(@delegate))
+          @delegate = Class.new(config[DELEGATE] || DRb::DRbTCPSocket) do
+            class << self
+              attr_writer :delegate
+
+              def parse_uri(uri)
+                @delegate.parse_uri(uri)
+              end
+
+              def uri_option(uri, config)
+                @delegate.uri_option(uri, config)
+              end
+            end
+          end
+          @delegate.delegate = self
+        end
+        @delegate
+      end
+    end
+
+    attr_reader :signal_id, :uri
+
+    def initialize(uri, delegate)
+      super(delegate)
+      @uri = uri
+      @id = 0
+      @id_mutex = Mutex.new
+    end
+
+    def accept
+      while(__getobj__.instance_eval{@socket})
+        begin
+          connection = self.class.new(nil, __getobj__.accept)
+        rescue IOError
+          return nil
+        end
+        begin
+          type = connection.stream.read(1)
+        rescue
+          next
+        end
+        case type
+        when INCOMING_CONN
+          return connection
+        when OUTGOING_CONN
+          self.class.add_client_connection(connection.read_signal_id, connection)
+          next
+        when SIGNAL_CONN
+          new_id = nil
+          @id_mutex.synchronize do
+            new_id = (@id += 1)
+          end
+          client_server = ClientServerProxy.new(connection, new_id)
+          self.class.add_client_server(new_id, client_server)
+          client_server.write_signal_id
+          next
+        else
+          raise "Invalid type #{type}"
+        end
+      end
+    end
+
+    def read_signal_id
+      stream.read(4).unpack(ID_FORMAT).first
+    end
+  end
+end
+DRb::DRbProtocol.add_protocol(DRbFire::Protocol)