added message tests and documentation

hydra.gemspec

@@ -5,16 +5,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{hydra}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Nick Gauthier"]
-  s.date = %q{2010-01-26}
+  s.date = %q{2010-01-27}
   s.description = %q{Spread your tests over multiple machines to test your code faster.}
   s.email = %q{nick@smartlogicsolutions.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.rdoc",
+     "TODO"
   ]
   s.files = [
     ".document",
@@ -22,14 +23,20 @@ Gem::Specification.new do |s|
      "LICENSE",
      "README.rdoc",
      "Rakefile",
+     "TODO",
      "VERSION",
      "hydra.gemspec",
      "lib/hydra.rb",
+     "lib/hydra/io.rb",
+     "lib/hydra/message.rb",
+     "lib/hydra/message/runner_requests_file.rb",
      "lib/hydra/pipe.rb",
+     "lib/hydra/runner.rb",
      "lib/hydra/ssh.rb",
      "test/echo_the_dolphin.rb",
      "test/helper.rb",
      "test/test_pipe.rb",
+     "test/test_runner.rb",
      "test/test_ssh.rb"
   ]
   s.homepage = %q{http://github.com/ngauthier/hydra}
@@ -40,7 +47,9 @@ Gem::Specification.new do |s|
   s.test_files = [
     "test/test_ssh.rb",
      "test/helper.rb",
+     "test/test_message.rb",
      "test/test_pipe.rb",
+     "test/test_runner.rb",
      "test/echo_the_dolphin.rb"
   ]
 

lib/hydra/io.rb

@@ -1,6 +1,12 @@
 module Hydra #:nodoc:
+  # Module that implemets methods that auto-serialize and deserialize messaging
+  # objects.
   module MessagingIO
-    # Read a line from the input IO object.
+    # Read a Message from the input IO object. Automatically build
+    # a message from the response and return it.
+    #
+    #  IO.gets
+    #    => Hydra::Message # or subclass
     def gets
       raise IOError unless @reader
       message = @reader.gets
@@ -8,7 +14,9 @@ module Hydra #:nodoc:
       return Message.build(eval(message.chomp))
     end
 
-    # Write a line to the output IO object
+    # Write a Message to the output IO object. It will automatically
+    # serialize a Message object.
+    #  IO.write Hydra::Message.new
     def write(message)
       raise IOError unless @writer
       raise UnprocessableMessage unless message.is_a?(Hydra::Message)
@@ -19,13 +27,18 @@ module Hydra #:nodoc:
       end
     end
 
+    # Closes the IO object.
     def close
       @reader.close if @reader
       @writer.close if @writer
     end
 
+    # IO will return this error if it cannot process a message.
+    # For example, if you tried to write a string, it would fail,
+    # because the string is not a message.
     class UnprocessableMessage < RuntimeError
       attr_accessor :message
+      # Allow a custom message for the exception.
       def initialize(message = "Message expected")
         @message = message    
       end

lib/hydra/message.rb

@@ -1,18 +1,45 @@
 module Hydra #:nodoc:
-  class Message #:nodoc:
+  # Base message object. Used to pass messages with parameters around
+  # via IO objects.
+  #   class MyMessage < Hydra::Message
+  #     attr_accessor :my_var
+  #     def serialize
+  #       super(:my_var => @my_var)
+  #     end
+  #   end
+  #   m = MyMessage.new(:my_var => 'my value')
+  #   m.my_var
+  #     => "my value"
+  #   m.serialize
+  #     => "{:class=>TestMessage::MyMessage, :my_var=>\"my value\"}"
+  #   Hydra::Message.build(eval(@m.serialize)).my_var
+  #     => "my value"
+  class Message
+    # Create a new message. Opts is a hash where the keys
+    # are attributes of the message and the values are
+    # set to the attribute.
     def initialize(opts = {})
       opts.each do |k,v|
-        self.send(k,v)
+        self.send("#{k}=",v)
       end
     end
+
+    # Build a message from a hash. The hash must contain
+    # the :class symbol, which is the class of the message
+    # that it will build to.
     def self.build(hash)
       hash.delete(:class).new(hash)
     end
 
+    # Serialize the message for output on an IO channel.
+    # This is really just a string representation of a hash
+    # with no newlines. It adds in the class automatically
     def serialize(opts = {})
       opts[:class] = self.class
       opts.inspect
     end
   end
 end
+
 require 'hydra/message/runner_requests_file'
+

lib/hydra/pipe.rb

@@ -2,15 +2,19 @@ require 'hydra/io'
 module Hydra #:nodoc:
   # Read and write between two processes via pipes. For example:
   #   @pipe = Hydra::Pipe.new
-  #   Process.fork do
+  #   @child = Process.fork do
   #     @pipe.identify_as_child
-  #     sleep(1)
-  #     puts "A message from my parent:\n#{@pipe.gets}"
+  #     puts "A message from my parent:\n#{@pipe.gets.text}"
   #     @pipe.close
   #   end
   #   @pipe.identify_as_parent
-  #   @pipe.write "Hello, Child!"
+  #   @pipe.write Hydra::Messages::TestMessage.new(:text => "Hello!")
   #   @pipe.close
+  #
+  # Note that the TestMessage class is only available in tests, and
+  # not in Hydra by default.
+  #
+  #
   # When the process forks, the pipe is copied. When a pipe is
   # identified as a parent or child, it is choosing which ends
   # of the pipe to use.

lib/hydra/runner.rb

@@ -1,5 +1,8 @@
 module Hydra #:nodoc:
+  # Hydra class responsible for running test files
   class Runner
+    # Boot up a runner. It takes an IO object (generally a pipe from its
+    # parent) to send it messages on which files to execute.
     def initialize(io)
       @io = io
       @io.write Hydra::Messages::RunnerRequestsFile.new

lib/hydra/ssh.rb

@@ -2,20 +2,17 @@ require 'open3'
 require 'hydra/io'
 module Hydra #:nodoc:
   # Read and write with an ssh connection. For example:
-  #  @ssh = Hydra::SSH.new('nick@nite')
-  #  @ssh.write("echo hi")
-  #  puts @ssh.gets
-  #    => hi
+  #   @ssh = Hydra::SSH.new(
+  #     'localhost', # connect to this machine
+  #     '/home/user', # move to the home directory
+  #     "ruby hydra/test/echo_the_dolphin.rb" # run the echo script
+  #   )
+  #   @message = Hydra::Messages::TestMessage.new("Hey there!")
+  #   @ssh.write @message
+  #   puts @ssh.gets.text
+  #     => "Hey there!"
   #
-  # You can also use this to launch an interactive process. For
-  # example:
-  #  @ssh = Hydra::SSH.new('nick@nite')
-  #  @ssh.write('irb')
-  #  @ssh.write("5+3")
-  #  @ssh.gets
-  #    => "5+3\n"       # because irb echoes commands
-  #  @ssh.gets
-  #    => "8"           # the output from irb
+  # Note that what ever process you run should respond with Hydra messages.
   class SSH
     include Open3
     include Hydra::MessagingIO

test/test_message.rb

@@ -0,0 +1,31 @@
+require File.join(File.dirname(__FILE__), 'helper')
+
+class TestMessage < Test::Unit::TestCase
+  class MyMessage < Hydra::Message
+    attr_accessor :my_var
+    def serialize
+      super(:my_var => @my_var)
+    end
+  end
+
+  context "with a message" do
+    setup do
+      @m = MyMessage.new(:my_var => 'my value')
+    end
+    should "set values" do
+      assert_equal 'my value', @m.my_var
+    end
+    should "serialize" do
+      assert_equal(
+        "{:class=>TestMessage::MyMessage, :my_var=>\"my value\"}",
+        @m.serialize
+      )
+    end
+    should "build from serialization" do
+      assert_equal(
+        @m.my_var,
+        Hydra::Message.build(eval(@m.serialize)).my_var
+      )
+    end
+  end
+end