bane 0.2.0 → 0.3.0

data/README.md

@@ -2,11 +2,15 @@
 
 Bane is a test harness used to test your application's interaction with other servers.  It is based upon the material from Michael Nygard's ["Release It!"](http://www.pragprog.com/titles/mnee/release-it) book as described in the "Test Harness" chapter.
 
+## Why Use Bane?
+
+If you are building an application, you may depend on third-party servers or web services for your data. Most of the time these services are reliable, but at some point they will behave in an unusual manner - such as connecting but never respond, sending data very slowly, or sending an unexpected response. To ensure your application survives these scenarios, you should test your application against these bad behaviors. Bane helps you recreate these scenarios by standing in for your third-party servers and responding in several nefarious ways.
+
 ## Setup
 
 Bane is available as a gem.  Install it with
 
-  `sudo gem install bane`
+  `gem install bane`
 
 Note that Bane installs an executable, `bane`.  Simply invoke `bane` with no arguments to get a usage description.
 
@@ -26,24 +30,37 @@ Bane is designed with a few usage scenarios in mind:
 
    Example: `$ bane 3000`
 
-4. Advanced Configuration using Ruby.  If you want to modify some of the defaults used in the included behaviors, you can initialize Bane with a Hash of port numbers, behavior names, and configuration parameters.  For example, you might want to specify a response for the FixedResponse behavior:
+4. Advanced Configuration using Ruby.  If you want to modify some of the defaults used in the included behaviors, you can create a Ruby script to invoke Bane.  For example, you might want to specify a response for the FixedResponse behavior:
 
    Example:
 
-        require 'bane'
+```
+require 'bane'
+
+include Bane
+
+launcher = Launcher.new(
+  [BehaviorServer.new(3000, Behaviors::FixedResponse.new(:message => "Shall we play a game?"))])
+launcher.start
+launcher.join
+```
+
+   See the `examples`directory for more examples.  For a list of options supported by the
+   included behaviors, see the source for the behaviors in `Bane::Behaviors` at `lib/bane/behaviors.rb`.
+
+## Listening on all hosts
+
+By default, Bane will listen only to connections on localhost (127.0.0.1).
 
-        include Bane
-        include Behaviors
+To listen on all hosts (0.0.0.0), start Bane from the command line with the `-a` or `--listen-on-all-hosts` option.  For more command line help, run `bane -h` or `bane --help`.
 
-        launcher = Launcher.new(Configuration(
-                3000 => {:behavior => FixedResponse, :message => "Shall we play a game?"},
-              )
-        )
-        launcher.start
-        launcher.join
+## Keeping the Connection Open
 
-   See `examples/specify_behavior_options.rb` for another example.  For a list of options supported by the
-   basic behaviors, see the source for the behaviors in `Bane::Behaviors` at `lib/bane/behaviors.rb`.
+By default, the socket behaviors that send any data will close the connection immediately after sending the response.  There are variations of these behaviors available that end with `ForEachLine` which will wait for a line of input (using IO's `gets`), respond, then return to the waiting for input state.
+
+For example, if you want to send a static response and then close the connection immediately, use `FixedResponse`.  If you want to keep the connection open and respond to every line of input with the same data, use `FixedResponseForEachLine`.  Note that these behaviors will never close the connection; they will happily respond to every line of input until you stop Bane.
+
+If you are implementing a new behavior, you should consider whether or not you would like to provide another variation which keeps a connection open and responds after every line of input.  If so, create the basic behavior which responds and closes the connection immediately, then create another behavior which includes the `ForEachLine` module.  See the source in `lib/bane/behaviors.rb` for some examples.
 
 ## Background
 
@@ -76,20 +93,3 @@ TCP packets at a low level; which may require a C or C++ extension.
 * The connection can be established, but packets could be lost causing retransmit delays
 * The connection can be established, but the remote end never acknowledges receiving a packet, causing endless retransmits
 
-## Design
-
-Bane Behaviors are simple objects which implement the Strategy pattern.  This makes them
-simple to unit test and allows them to be independent of the underlying server implementation.
-Bane currently serves all Behaviors using Ruby's built-in GServer, which provides a simple
-multi-threaded TCP server.  Behaviors currently:
-
-* Accept an IO stream used to read from or send a response.
-* Accept a hash of configuration options to allow overriding of default behavior parameters.
-* Provide a meaningful name to appear in the Bane log.  This is especially helpful if your application
-  under test dies and you'd like to identify which behavior killed it.
-
-To enable support of different types of behaviors such as HTTP responses or low-level TCP packet
-munging, a different base server instead of GServer may be required.  In that case, it should
-be possible to change how Behaviors are associated with a server, perhaps by making
-Behaviors extend a server base class.
-

data/Rakefile

@@ -1,60 +1,51 @@
+# encoding: utf-8
+
 require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
 require 'rake'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "bane"
-    gem.summary = "A test harness for socket connections based upon ideas from Michael Nygard's 'Release It!'"
-    gem.description = <<-END
-      Bane is a test harness used to test your application's interaction with
-      other servers. It is based upon the material from Michael Nygard's "Release
-      It!" book as described in the "Test Harness" chapter.
-    END
-    gem.authors = ["Daniel Wellman"]
-    gem.email = "dan@danielwellman.com"
-    gem.homepage = "http://github.com/danielwellman/bane"
-    gem.files = FileList[ 'lib/**/*', 'bin/*', 'test/**/*', 'examples/*',
-      'Rakefile' ]
-    gem.add_development_dependency('mocha', '>= 0.9.8')
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "bane"
+  gem.homepage = "http://github.com/danielwellman/bane"
+  gem.license = "BSD"
+  gem.summary = "A test harness for socket connections based upon ideas from Michael Nygard's 'Release It!'"
+  gem.description = <<-END
+    Bane is a test harness used to test your application's interaction with
+    other servers. It is based upon the material from Michael Nygard's "Release
+    It!" book as described in the "Test Harness" chapter.
+  END
+  gem.authors = ["Daniel Wellman"]
+  gem.email = "dan@danielwellman.com"
+  gem.files = FileList[ 'lib/**/*', 'bin/*', 'test/**/*', 'examples/*',
+    'Rakefile' ]
 end
+Jeweler::RubygemsDotOrgTasks.new
+
+
 
 require 'rake/testtask'
-desc "Run all tests"
-Rake::TestTask.new do |test|
+Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
   test.test_files =  FileList['test/**/*_test.rb']
   test.verbose    =  true
 end
 
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
-
-
-task :test => :check_dependencies
-
 task :default => :test
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "bane #{version}"
+  rdoc.title = "list #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/TODO

@@ -1,13 +1,21 @@
-- Remove some duplication / clarify the ConfigurationParser class as needed
-- Dynamically create new behaviors like "SlowResponseForEachLine" by using Module.const_missing
-- Use ActiveSupport or create simple extensions for time durations (seconds, minutes, etc.)
-- Write the bad TCP/IP behaviors - using something like C/C++.
-- Write the remaining bad HTTP behaviors.  In addition, we may want to replace the NaiveHttpResponse with something
-  from the standard Ruby library, so that there's less code in this project, and so we know that we're
-  following the HTTP protocol.
+Features:
+- Quieter exits on Ctrl-C (than plain stack trace)
+
+Design questions / Ideas:
+- Make BasicBehavior a module called Behavior, and include that in each behavior?
+- Is there a natural separation in Configuration between parsing arguments and instantiating/finding behaviors?
+  In particular, mocking "new" on a class seems to be a smell -- at least because I keep forgetting that 'new' must
+  return an object, and my mocks didn't do that (see CommandLineConfigurationTest, and the messier ConfigurationParserTest)
+- Explore the ServiceRegistry usage -- should "find" behaviors be there? Printing?
+- Decide if the current behaviors should be tied more directly to BehaviorServer, via subclassing or some other way.
+- Figure out where the logger configuration logic belongs in the Launcher/BehaviorServer relationship
+- Should the default logger go to STDERR or STDOUT?
+- Break the Behaviors out into several files and test files?
 - Log every request to the server/behavior, in addition to open, close.  For this to work, it would have to be the
   behavior's responsibility, since GServer#serve gets called only once for the lifetime of the connection.
 
-Ideas:
-- Make the Launcher use a Factory to create the server given a dependency, rather than depending directly on the
-  DelegatingGServer class.  This would make it possible to swap the base server implementation more easily.
+Future Behaviors:
+- Create a more configurable version of the DelugeResponse which allows for a header, footer, content and times to repeat.
+- Write the remaining bad HTTP behaviors.  In addition, we may want to replace the NaiveHttpResponse with something
+  from the standard Ruby library, so that there's less code in this project, and so we know that we're
+  following the HTTP protocol.

data/bin/bane

@@ -3,15 +3,20 @@
 $LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
 require 'bane'
 
-if ARGV.empty?
-  puts "Usage: bane port_number <servers>"
-  puts
-  puts "All behaviors:"
-  behavior_names = Bane::ServiceRegistry.all_servers.map(&:simple_name)
-  behavior_names.sort.each { |behavior| puts " - #{behavior}" }
-else
-  launcher = Bane::Launcher.new(Configuration(*ARGV))
-  launcher.start
-  launcher.join
+config = Bane::CommandLineConfiguration.new()
+begin
+  servers = config.parse(ARGV)
+rescue Bane::ConfigurationError => ce
+  puts ce.message
+  puts config.usage
+  exit 1
 end
 
+if servers.empty?
+  puts config.usage
+  exit 0
+end
+
+launcher = Bane::Launcher.new(servers)
+launcher.start
+launcher.join

data/examples/multiple_behaviors.rb

@@ -0,0 +1,24 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'bane'
+
+include Bane
+
+# This example creates several behavior listening on distinct ports.
+# Note the FixedResponse port specifies to listen to all hosts (0.0.0.0), all
+# other servers listen to localhost only by default (127.0.0.1).
+
+close_immediately = Behaviors::CloseImmediately.new
+never_respond = Behaviors::NeverRespond.new
+fixed_response = Behaviors::FixedResponse.new(:message => "OK")
+
+launcher = Launcher.new([BehaviorServer.new(3000, close_immediately),
+                        BehaviorServer.new(8000, never_respond),
+                        BehaviorServer.new(8080, fixed_response, BehaviorServer::ALL_INTERFACES)])
+launcher.start
+# To run until interrupt, use the following line:
+#launcher.join
+
+# For examples, we'll let these sleep for a few seconds and then shut down'
+sleep 10
+launcher.stop
+

data/examples/readme_example.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'bane'
+
+include Bane
+
+launcher = Launcher.new(
+        [BehaviorServer.new(3000, Behaviors::FixedResponse.new(:message => "Shall we play a game?"))])
+launcher.start
+launcher.join

data/examples/single_behavior.rb

@@ -0,0 +1,18 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'bane'
+
+include Bane
+
+# This example creates a single behavior listening on port 3000.
+# Note that the behavior, CloseAfterPause, specifies a default duration to pause - 60 seconds.
+
+behavior = BehaviorServer.new(3000, Behaviors::CloseAfterPause.new(:duration => 60))
+launcher = Launcher.new([behavior])
+launcher.start
+# To run until interrupt, use the following line:
+#launcher.join
+
+# For examples, we'll let these sleep for a few seconds and then shut down'
+sleep 10
+launcher.stop
+

data/lib/bane.rb

@@ -2,7 +2,7 @@ require 'bane/compatibility'
 require 'bane/service_registry'
 require 'bane/behaviors'
 require 'bane/launcher'
-require 'bane/delegating_gserver'
-require 'bane/configuration'
+require 'bane/behavior_server'
+require 'bane/command_line_configuration'
 require 'bane/configuration_parser'
 require 'bane/naive_http_response'

data/lib/bane/{delegating_gserver.rb → behavior_server.rb}

@@ -1,19 +1,24 @@
 require 'gserver'
 
 module Bane
-  class DelegatingGServer < GServer
-    def initialize(port, behavior, options = {}, logger = $stderr)
-      super(port)
+  class BehaviorServer < GServer
+
+    ALL_INTERFACES = "0.0.0.0"
+
+    def initialize(port, behavior, host = BehaviorServer::DEFAULT_HOST)
+      super(port, host)
       @behavior = behavior
-      @options = options
       self.audit = true
-      self.stdlog = logger
     end
 
     def serve(io)
-      @behavior.serve(io, @options)
+      @behavior.serve(io)
     end
 
+    def to_s
+      "<Bane::BehaviorServer: port=#{@port}, behavior=#{@behavior.class}>"
+    end
+    
     protected
 
     alias_method :original_log, :log

data/lib/bane/behaviors.rb

@@ -16,16 +16,16 @@ module Bane
     # a "while(io.gets)" loop, which reads a line from the input and
     # then performs the given behavior.
     module ForEachLine
-      def serve(io, options)
+      def serve(io)
         while (io.gets)
-          super(io, options)
+          super(io)
         end
       end
     end
 
     # Closes the connection immediately after a connection is made.
     class CloseImmediately < BasicBehavior
-      def serve(io, options)
+      def serve(io)
         # do nothing
       end
     end
@@ -35,10 +35,12 @@ module Bane
     # Options:
     #   - duration: The number of seconds to wait before disconnect.  Default: 30
     class CloseAfterPause < BasicBehavior
-      def serve(io, options)
-        options = {:duration => 30}.merge(options)
+      def initialize(options = {})
+        @options = {:duration => 30}.merge(options)
+      end
 
-        sleep(options[:duration])
+      def serve(io)
+        sleep(@options[:duration])
       end
     end
 
@@ -47,10 +49,12 @@ module Bane
     # Options:
     #   - message: The response message to send. Default: "Hello, world!"
     class FixedResponse < BasicBehavior
-      def serve(io, options)
-        options = {:message => "Hello, world!"}.merge(options)
+      def initialize(options = {})
+        @options = {:message => "Hello, world!"}.merge(options)
+      end
 
-        io.write options[:message]
+      def serve(io)
+        io.write @options[:message]
       end
     end
 
@@ -60,7 +64,7 @@ module Bane
 
     # Sends a newline character as the only response 
     class NewlineResponse < BasicBehavior
-      def serve(io, options)
+      def serve(io)
         io.write "\n"
       end
     end
@@ -71,7 +75,7 @@ module Bane
 
     # Sends a random response.
     class RandomResponse < BasicBehavior
-      def serve(io, options)
+      def serve(io)
         io.write random_string
       end
 
@@ -92,10 +96,13 @@ module Bane
     #  - message: The response to send. Default: "Hello, world!"
     #  - pause_duration: The number of seconds to pause between each character. Default: 10 seconds
     class SlowResponse < BasicBehavior
-      def serve(io, options)
-        options = {:message => "Hello, world!", :pause_duration => 10}.merge(options)
-        message = options[:message]
-        pause_duration = options[:pause_duration]
+      def initialize(options = {})
+        @options = {:message => "Hello, world!", :pause_duration => 10}.merge(options)
+      end
+
+      def serve(io)
+        message = @options[:message]
+        pause_duration = @options[:pause_duration]
 
         message.each_char do |char|
           io.write char
@@ -111,7 +118,7 @@ module Bane
     # Accepts a connection and never sends a byte of data.  The connection is
     # left open indefinitely.
     class NeverRespond < BasicBehavior
-      def serve(io, options)
+      def serve(io)
         loop { sleep 1 }
       end
     end
@@ -121,9 +128,11 @@ module Bane
     # Options
     #  - length: The size in bytes of the response to send. Default: 1,000,000 bytes
     class DelugeResponse < BasicBehavior
-      def serve(io, options)
-        options = {:length => 1_000_000}.merge(options)
-        length = options[:length]
+      def initialize(options = {})
+        @options = {:length => 1_000_000}.merge(options)
+      end
+      def serve(io)
+        length = @options[:length]
 
         length.times { io.write('x') }
       end
@@ -150,7 +159,7 @@ module Bane
 </html>
 EOF
 
-      def serve(io, options)
+      def serve(io)
         io.gets # Read the request before responding
         response = NaiveHttpResponse.new(401, "Unauthorized", "text/html", UNAUTHORIZED_RESPONSE_BODY)
         io.write(response.to_s)