Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updating README and TODO. Using Markdown for README.

  • Loading branch information...
commit ad380469b056a59e885505536d4c05b97a7c890d 1 parent 6b5f40a
@danielwellman authored
Showing with 89 additions and 69 deletions.
  1. +0 −65 README
  2. +87 −0 README.md
  3. +2 −1  TODO
  4. +0 −3  lib/bane/launcher.rb
View
65 README
@@ -1,65 +0,0 @@
-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.
-
-Bane is designed with three usage scenarios in mind:
-
-1. Quick Start with a specific behavior from the command line. If your application talks to another server on a given port, you can start bane from the command line by specifying the desired port and a name of server behavior. For example, if your server talks to a third-party server on port 8080, you could start the "Never Respond" behavior on port 8080 to observe how your application behaves.
-
-Example: $ bin/bane 8080 NeverRespond
-
-2. Quick Start with a variety of behaviors from the command line. If you just want a general purpose test harness to run, and you can easily control the ports that your application talks to, you can start bane up with a base port number and it will start all its known behaviors. This way you can leave bane running and tweak your application to talk to each of the various behaviors.
-
-Example: $ bin/bane 3000
-
-3. 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:
-
-Example:
-
-require 'bane'
-
-include Bane
-include Behaviors
-
-launcher = Launcher.new(Configuration(
- 3000 => {:behavior => FixedResponse, :message => "Shall we play a game?"},
- )
-)
-launcher.start
-launcher.join
-
-
-See examples/specify_behavior_options.rb for another example.
-
----
-
-Here is some information from "Release It!" which explains the motivations of bane.
-
-A list of possible test harness behaviors from "Release It!" p. 126 ("Test Harness"):
-
-"... the socket connection is succeptible to the following failures:
-
-* It can be refused.
-* It 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 the remote end never sends a byte of 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
-* The service can accept a request, send response headers (supposing HTTP), and ndever send the response body.
-* The service can send one byte of the response every thirty seconds.
-* The service can send a response of HTML instead of the expected XML.
-* The service can send megabytes when kilobytes are expected.
-* The service can refuse all authentication credentials.
-
-The failures fall into distinct categories: network transport problems, network protocol problems, application protocol problems, and application logic problems. ..."
-
-
-Other behavior listed (p. 128):
-
-"Many kinds of bad behavior will be similar for different applications and protocols. For example, refusing connections, connecting slowly, and accepting requests without reply would apply to any socket protocol: HTTP, RMI, or RPC."
-
-"... accept connections but never reply..."
-"... gets a connection and a reply, but the reply is from /dev/random ..."
-"... open a connection and then drop it immediately ..."
-
-
View
87 README.md
@@ -0,0 +1,87 @@
+# 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.
+
+## Usage
+
+Bane is designed with three usage scenarios in mind:
+
+1. Quick start with a specific behavior from the command line. If your application talks to another server on a given port, you can start bane from the command line by specifying the desired port and a name of server behavior. For example, if your server talks to a third-party server on port 8080, you could start the "Never Respond" behavior on port 8080 to observe how your application behaves.
+
+ Example: `$ bin/bane 8080 NeverRespond`
+
+ You may also specify multiple behaviors, which will start on consecutive ports:
+
+ Example: `$ bin/bane 8080 NeverRespond CloseImmediately`
+
+2. Quick start with a variety of behaviors from the command line. If you just want a general purpose test harness to run, and you can easily control the ports that your application talks to, you can start bane up with a base port number and it will start all its known behaviors. This way you can leave bane running and tweak your application to talk to each of the various behaviors.
+
+ Example: `$ bin/bane 3000`
+
+3. 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:
+
+ Example:
+
+ require 'bane'
+
+ include Bane
+ include Behaviors
+
+ launcher = Launcher.new(Configuration(
+ 3000 => {:behavior => FixedResponse, :message => "Shall we play a game?"},
+ )
+ )
+ launcher.start
+ launcher.join
+
+ 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`.
+
+## Background
+
+See the "Test Harness" chapter from "Release It!" to read about the inspiration of Bane.
+
+The following behaviors are currently supported in Bane, with the name of the behavior after the description in parenthesis.
+Note that these are simple protocol-independent socket behaviors:
+
+* The connection can be established, but the remote end never sends a byte of data (NeverRespond)
+* The service can send one byte of the response every thirty seconds (SlowResponse)
+* The server establishes a connection but sends a random reply (RandomResponse)
+* 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 following behaviors are not yet supported; they require the configuration of an HTTP server.
+This should be possible to build and might require a slight change in how Behaviors are served.
+
+* The service can accept a request, send response headers (supposing HTTP), and never send the response body.
+* The service can send a response of HTML instead of the expected XML.
+* The service can refuse all authentication credentials.
+
+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.
+
+* 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.
+
+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.
+
View
3  TODO
@@ -1,10 +1,11 @@
-- Rectify the Configuration/ConfigurationParser split -- Remove some duplication / clarify the ConfigurationParser class as needed
+- Remove some duplication / clarify the ConfigurationParser class as needed
- Dynamically create new behaviors like "SlowResponseForEachLine" by using Module.const_missing
- 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.
- Use ActiveSupport or other extensions for time durations (seconds, minutes, etc.)
- Make and publish a gem
- Write the bad TCP/IP behaviors - using something like C/C++.
+- Write the bad HTTP behaviors - this may require using something other than GServer for the Behavior server.
Ideas:
- Make the Launcher use a Factory to create the server given a dependency, rather than depending directly on the
View
3  lib/bane/launcher.rb
@@ -20,9 +20,6 @@ def stop
@running_servers.each { |server| server.stop }
end
- private
-
-
end
end
Please sign in to comment.
Something went wrong with that request. Please try again.