bane 0.1.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f238270f71940d8a67a36a5a57f99c0ba77f05ba8c5af3a9ea9805c1d527d12
+  data.tar.gz: 7da73073b9fcd740d5c64e609d963191ccd411b20dd2fbd700618b9c21744cd1
+SHA512:
+  metadata.gz: 59df1b491b22c50e6ab0cd4adeaa633f6d3089c05b489fafeffad196c5ce75376940454575d3d208e65efb7b5cf618ceedaae0fd9cec87de0f37108149cab0d8
+  data.tar.gz: 662f09c29e1dbe1da105fac39891ee68893afc014dd1f56f49f099986c13ef8c3d7a0964b470bd495900310b104e8a34f28cc1d86d30337b202e5a377a4ddf2e

data/HISTORY.md

@@ -0,0 +1,49 @@
+# master
+
+## 1.0.0
+
+### Changed
+ * Support Ruby 2.5+. This meant adding a dependency on 'gserver', which was moved out of the standard library.
+
+## 0.4.0
+
+### Added
+ * The EchoResponse behavior which replies with each line sent
+ * The TimeoutInListenQueue server which binds to a port but never calls listen(2)
+ * Trap SIGINT to gracefully stop servers without a messy exception stacktrace
+
+### Removed
+ * The fancy, flexible ConfigurationParser has been deleted. Command-line invocation now uses the CommandLineConfiguration parser.  For programmatic invocation, see the examples.
+ * Ruby 1.8.7 support
+
+### Changed
+  * Rearranged packages to create Bane::Behaviors::Servers and Bane::Beaviors::Responders.  Servers may be started and stopped; Responders simply interact with an already connected socket.
+  * Added Bane::Behaviors::Servers::LOCALHOST (127.0.0.1) and deprecated Bane::Behaviors::Servers::DEFAULT_HOST; please use LOCALHOST when specifying a host to listen on.
+
+## 0.3.0
+
+### Added
+ * Servers can now listen on all hosts or localhost via the command-line options -a / --listen-on-all-hosts or -l / --listen-on-localhost.  The default is to listen on localhost.
+
+
+### Changed
+ * Behaviors receive their parameters through their constructors instead of being passed via the serve method.  That is,
+  the serve(io, options) method has been changed to serve(io).  Behaviors that need to accept user-specified parameters
+  should accept them via constructor arguments, and should provide a default version since the command-line interface
+  does not specify options.  e.g.
+
+```
+class MyBehavior
+   def initialize(options = {})
+   ...
+```
+
+* BehaviorServer no longer accepts options; instead these are created with the Behavior objects.
+* Configuration() and ConfigurationParser class are deprecated and will be removed in the next release.  Instead of 
+  using these classes, please directly instantiate a BehaviorServer with the required arguments.  This class is being
+  deprecated and removed because the flexibility of the code creates a structure that is harder to read and maintain.
+  I'm also not sure anyone is using this method -- if so, please open a GitHub Issue and let me know if you're using 
+  it -- and if so, how.
+
+
+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010, Daniel J. Wellman
+Copyright (c) 2021, Daniel J. Wellman
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

data/README.md

@@ -1,15 +1,23 @@
 # Bane
 
+[![Build Status](https://secure.travis-ci.org/danielwellman/bane.png)](http://travis-ci.org/danielwellman/bane) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/danielwellman/bane)
+
 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
+Bane is available as a Ruby 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.
 
+Bane requires Ruby 2.5 or later.
+
 ## Usage
 
 Bane is designed with a few usage scenarios in mind:
@@ -26,24 +34,38 @@ 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::Responders::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 `lib/bane/behaviors`; note that you will find both
+   servers (that bind to sockets directly) and responders (that assume a running TCP server and communicate with a socket connection).
 
-        include Bane
-        include Behaviors
+## Listening on all hosts
 
-        launcher = Launcher.new(Configuration(
-                3000 => {:behavior => FixedResponse, :message => "Shall we play a game?"},
-              )
-        )
-        launcher.start
-        launcher.join
+By default, Bane will listen only to connections on localhost (127.0.0.1).
 
-   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`.
+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`.
+
+## Keeping the Connection Open
+
+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/responders/fixed_response.rb` for some examples.
 
 ## Background
 
@@ -58,6 +80,7 @@ Note that these are simple protocol-independent socket behaviors:
 * The server accepts a connection and then drops it immediately (CloseImmediately)
 * The service can send megabytes when kilobytes are expected. (rough approximation with the DelugeReponse)
 * The service can refuse all authentication credentials. (HttpRefuseAllCredentials)
+* The request can sit in a listen queue until the caller times out. (TimeoutInListenQueue)
 
 The following behaviors are not yet supported; they require the configuration of an HTTP server.
 See the implementation of HttpRefuseAllCredentials for a simple example of an HTTP behavior.
@@ -66,30 +89,17 @@ See the implementation of HttpRefuseAllCredentials for a simple example of an HT
 * The service can send a response of HTML instead of the expected XML.
 
 The following behaviors are not yet supported. These require the ability to manipulate
-TCP packets at a low level; which may require a C or C++ extension.
+TCP packets at a low level, which may require a C or C++ extension or raw sockets.
 
 * The connection can be refused.
-* The request can sit in a listen queue until the caller times out.
 * The remote end can reply with a SYN/ACK and then never send any data.
 * The remote end can send nothing but RESET packets.
 * The remote end can report a full receive window and never drain the data.
 * 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.
+## Support
 
-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.
+<a href="http://www.cyrusinnovation.com/"><img src="http://www.cyrusinnovation.com/marketing/logo.png" alt="Cyrus"></a>
 
+Thank you to [Cyrus](http://www.cyrusinnovation.com/) for supporting the development of this project.

data/TODO

@@ -1,13 +1,18 @@
-- 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:
+
+Design questions / Ideas:
+- Figure out where the logger configuration logic belongs in the Launcher/BehaviorServer relationship
+- Should the default logger go to STDERR or STDOUT?
 - 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.
+- If we extract a commong logger, we might use that to test for proper disconnection in NeverRespondTest#test_disconnects_after_client_closes_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.
+- Have a tiny listen queue (queue size 0) and a connection never gets into the queue
+- Have a giant listen queue (queue size max?) and only one thread processing -- times out in the listen queue
+- Close the write part of the connection, but not the read
+- Close the read part of the connection, but not the write

data/bin/bane

@@ -1,17 +1,14 @@
 #!/usr/bin/env ruby
 
-$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
+parser = Bane::CommandLineConfiguration.new(Bane.find_makeables)
+servers = parser.process(ARGV) do |error_message|
+  puts error_message
+  exit 1
 end
 
+launcher = Bane::Launcher.new(servers)
+launcher.start
+trap("SIGINT") { Thread.new { launcher.stop; exit } }
+launcher.join

data/lib/bane/arguments_parser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Bane
+  class ArgumentsParser
+    def initialize(makeable_names)
+      @makeable_names = makeable_names
+      @options = {host: default_host}
+      @option_parser = init_option_parser
+    end
+
+    def parse(args)
+      @option_parser.parse!(args)
+
+      raise ConfigurationError, "Missing arguments" if args.empty?
+
+      port = parse_port(args[0])
+      behaviors = args.drop(1)
+      ParsedArguments.new(port, @options[:host], behaviors)
+    rescue OptionParser::InvalidOption => io
+      raise ConfigurationError, io.message
+    end
+
+    def usage
+      @option_parser.help
+    end
+
+    private
+
+    def init_option_parser
+      OptionParser.new do |opts|
+        opts.banner = 'Usage: bane [options] port [behaviors]'
+        opts.separator ''
+        opts.on('-l', '--listen-on-localhost',
+                "Listen on localhost, (#{default_host}). [default]") do
+          @options[:host] = default_host
+        end
+        opts.on('-a', '--listen-on-all-hosts', "Listen on all interfaces, (#{all_interfaces})") do
+          @options[:host] = all_interfaces
+        end
+        opts.separator ''
+        opts.separator 'All behaviors:'
+        opts.separator @makeable_names.sort.map { |title| " - #{title}" }.join("\n")
+      end
+    end
+
+    def parse_port(port)
+      Integer(port)
+    rescue ArgumentError
+      raise ConfigurationError, "Invalid port number: #{port}"
+    end
+
+    def all_interfaces
+      Behaviors::Servers::ALL_INTERFACES
+    end
+
+    def default_host
+      Behaviors::Servers::LOCALHOST
+    end
+  end
+
+  class ParsedArguments
+
+    attr_reader :port, :host, :behaviors
+
+    def initialize(port, host, behaviors)
+      @host = host
+      @port = port
+      @behaviors = behaviors
+    end
+
+  end
+
+end

data/lib/bane/behavior_maker.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Bane
+
+  class BehaviorMaker
+    def initialize(makeables)
+      @makeables = makeables
+    end
+
+    def create(behavior_names, starting_port, host)
+      behavior_names
+        .map { |behavior| makeables.fetch(behavior) { raise UnknownBehaviorError.new(behavior) } }
+        .map.with_index { |maker, index| maker.make(starting_port + index, host) }
+    end
+
+    def create_all(starting_port, host)
+      makeables.sort.map.with_index { |name_maker_pair, index| name_maker_pair.last.make(starting_port + index, host) }
+    end
+
+    private
+
+    attr_reader :makeables
+  end
+
+  class UnknownBehaviorError < RuntimeError
+    def initialize(name)
+      super "Unknown behavior: #{name}"
+    end
+  end
+
+  class ResponderMaker
+    def initialize(responder)
+      @responder = responder
+    end
+
+    def make(port, host)
+      Behaviors::Servers::ResponderServer.new(port, @responder.new, host)
+    end
+  end
+
+end

data/lib/bane/behaviors/responders/close_after_pause.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Accepts a connection, pauses a fixed duration, then closes the connection.
+      #
+      # Options:
+      #   - duration: The number of seconds to wait before disconnect.  Default: 30
+      class CloseAfterPause
+        def initialize(options = {})
+          @options = {duration: 30}.merge(options)
+        end
+
+        def serve(io)
+          sleep(@options[:duration])
+        end
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/close_immediately.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Closes the connection immediately after a connection is made.
+      class CloseImmediately
+        def serve(io)
+          # do nothing
+        end
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/deluge_response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends a large response.  Response consists of a repeated 'x' character.
+      #
+      # Options
+      #  - length: The size in bytes of the response to send. Default: 1,000,000 bytes
+      class DelugeResponse
+        def initialize(options = {})
+          @options = {length: 1_000_000}.merge(options)
+        end
+
+        def serve(io)
+          length = @options[:length]
+
+          length.times { io.write('x') }
+        end
+      end
+
+      class DelugeResponseForEachLine < DelugeResponse
+        include ForEachLine
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/echo_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      class EchoResponse
+        def serve(io)
+          while (input = io.gets)
+            io.write(input)
+          end
+          io.close
+        end
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/exported.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      EXPORTED = self.constants.map { |name| self.const_get(name) }.grep(Class)
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/fixed_response.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends a static response.
+      #
+      # Options:
+      #   - message: The response message to send. Default: "Hello, world!"
+      class FixedResponse
+        def initialize(options = {})
+          @options = {message: "Hello, world!"}.merge(options)
+        end
+
+        def serve(io)
+          io.write @options[:message]
+        end
+      end
+
+      class FixedResponseForEachLine < FixedResponse
+        include ForEachLine
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/for_each_line.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # This module can be used to wrap another behavior with
+      # a "while(io.gets)" loop, which reads a line from the input and
+      # then performs the given behavior.
+      module ForEachLine
+        def serve(io)
+          while (io.gets)
+            super(io)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/http_refuse_all_credentials.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends an HTTP 401 response (Unauthorized) for every request.  This
+      # attempts to mimic an HTTP server by reading a line (the request)
+      # and then sending the response.  This behavior responds to all
+      # incoming request URLs on the running port.
+      class HttpRefuseAllCredentials
+        UNAUTHORIZED_RESPONSE_BODY = <<EOF
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Bane Server</title>
+  </head>
+  <body>
+    <h1>Unauthorized</h1>
+  </body>
+</html>
+EOF
+
+        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)
+        end
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/never_respond.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Accepts a connection and never sends a byte of data.  The connection is
+      # left open indefinitely.
+      class NeverRespond
+        READ_TIMEOUT_IN_SECONDS = 2
+        MAXIMUM_BYTES_TO_READ = 4096
+
+        def serve(io)
+          loop do
+            begin
+              io.read_nonblock(MAXIMUM_BYTES_TO_READ)
+            rescue Errno::EAGAIN
+              IO.select([io], nil, nil, READ_TIMEOUT_IN_SECONDS)
+              retry # Ignore the result of IO select since we retry reads regardless of if there's data to be read or not
+            rescue EOFError
+              break
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/bane/behaviors/responders/newline_response.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends a newline character as the only response
+      class NewlineResponse
+        def serve(io)
+          io.write "\n"
+        end
+      end
+
+      class NewlineResponseForEachLine < NewlineResponse
+        include ForEachLine
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/random_response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends a random response.
+      class RandomResponse
+        def serve(io)
+          io.write random_string
+        end
+
+        private
+        def random_string
+          (1..rand(26)+1).map { |i| ('a'..'z').to_a[rand(26)] }.join
+        end
+
+      end
+
+      class RandomResponseForEachLine < RandomResponse
+        include ForEachLine
+      end
+
+    end
+  end
+end

data/lib/bane/behaviors/responders/slow_response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Bane
+  module Behaviors
+    module Responders
+
+      # Sends a fixed response character-by-character, pausing between each character.
+      #
+      # Options:
+      #  - message: The response to send. Default: "Hello, world!"
+      #  - pause_duration: The number of seconds to pause between each character. Default: 10 seconds
+      class SlowResponse
+        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
+            sleep pause_duration
+          end
+        end
+      end
+
+      class SlowResponseForEachLine < SlowResponse
+        include ForEachLine
+      end
+
+    end
+  end
+end