blitz 0.1.5 → 0.1.6

data/blitz.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{blitz}
-  s.version = "0.1.5"
+  s.version = "0.1.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["pcapr"]
-  s.date = %q{2011-04-18}
+  s.date = %q{2011-04-20}
   s.default_executable = %q{blitz}
   s.description = %q{Make load and performance testing a fun sport}
   s.email = %q{kowsik@gmail.com}

data/lib/blitz.rb

@@ -3,9 +3,9 @@ require 'couchrest'
 require 'hexy'
 require 'pp'
 
-class Blitz
+class Blitz # :nodoc:
     require 'blitz/helper'
-    Version = "0.1.5".freeze
+    Version = "0.1.6".freeze
         
     extend Blitz::Helper
     

data/lib/blitz/client.rb

@@ -1,5 +1,5 @@
 class Blitz
-class Client
+class Client # :nodoc:
     attr_reader :blitz
     
     def initialize user, apik, host='blitz.io'

data/lib/blitz/command.rb

@@ -3,23 +3,29 @@ require 'test/unit/assertions'
 # The default template string contains what was sent and received. Strip 
 # these out since we don't need them
 unless RUBY_VERSION =~ /^1.9/
-    class Test::Unit::Assertions::AssertionMessage
-        alias :old_template :template
+    module Test # :nodoc:
+        module Unit # :nodoc:
+            module Assertions # :nodoc:
+                class AssertionMessage # :nodoc:
+                    alias :old_template :template
 
-        def template
-            @template_string = ''
-            @parameters = []
-            old_template
+                    def template
+                        @template_string = ''
+                        @parameters = []
+                        old_template
+                    end
+                end
+            end
         end
     end
 else
-    module ::Test::Unit
+    module ::Test::Unit # :nodoc:
         AssertionFailedError = MiniTest::Assertion
     end
 end
 
 class Blitz
-class Command
+class Command # :nodoc:
     include Test::Unit::Assertions
     include Helper
 end

data/lib/blitz/command/api.rb

@@ -1,6 +1,6 @@
 class Blitz
 class Command
-class API < Command
+class API < Command # :nodoc:
     attr_accessor :credentials
         
     def cmd_init argv

data/lib/blitz/command/couch.rb

@@ -2,7 +2,7 @@ require 'couchrest'
 
 class Blitz
 class Command
-class Couch < Command
+class Couch < Command # :nodoc:
     attr_reader :urls
 
     def initialize

data/lib/blitz/command/curl.rb

@@ -1,6 +1,6 @@
 class Blitz
 class Command
-class Curl < Command
+class Curl < Command # :nodoc:
     def cmd_help argv
         help
     end
@@ -42,7 +42,7 @@ class Curl < Command
 
     def sprint args
         begin
-            job = ::Blitz::Curl::Sprint.execute args
+            job = ::Blitz::Curl::Sprint.queue args
             result = job.result
             print_sprint_result args, result
         rescue ::Blitz::Curl::Error::Authorize => e
@@ -106,7 +106,7 @@ class Curl < Command
             [ 'INT', 'STOP', 'HUP' ].each do |s| 
                 trap(s) { continue = false }
             end
-            job = ::Blitz::Curl::Rush.execute args
+            job = ::Blitz::Curl::Rush.queue args
             msg "rushing from #{job.region}..."
             job.result do |result|
                 print_rush_result result

data/lib/blitz/command/help.rb

@@ -1,6 +1,6 @@
 class Blitz
 class Command
-class Help < Command
+class Help < Command # :nodoc:
     def cmd_default argv
         puts
         msg "Usage: blitz <command> <options>"

data/lib/blitz/curl/error.rb

@@ -1,12 +1,23 @@
 class Blitz
 module Curl
-class Error < StandardError
+class Error < StandardError # :nodoc:
     def initialize json={}
         super json['reason'] || "Hmmm, something went wrong. Try again in a little bit?"
     end
     
+    # This exception is raised when you haven't authorized a rush against your app
     class Authorize < Error
-        attr_reader :scheme, :host, :port, :uuid
+        # The scheme used in the rush (http or httpss)
+        attr_reader :scheme
+        
+        # The host in the URL
+        attr_reader :host
+        
+        # The port (if specified) in the URL
+        attr_reader :port
+        
+        # The unique ID to use a URL path in your app for authorization to succeed
+        attr_reader :uuid
 
         def initialize json
             @scheme = json['scheme']
@@ -17,27 +28,35 @@ class Error < StandardError
         end
     end
     
+    # The base class for all exceptions thrown by the distributed scale engines
     class Region < Error
+        # The region from which the test was run
         attr_reader :region
         
-        def initialize json
+        def initialize json # :nodoc:
             @region = json['region']
             super
         end
     end
     
+    # This exception is raised when the DNS resolution fails
     class DNS < Region
     end
     
+    # This exception is raised when the connection to your app fails
     class Connect < Region
     end
     
+    # This exception is raised when the connection or the response times out
     class Timeout < Region
     end
 
+    # This exception is raised when the arguments to sprint or rush is invalid
     class Parse < Region
     end
     
+    # This exception is raised when you have an explicit status code check and
+    # the assertion fails
     class Status < Region
     end
 end

data/lib/blitz/curl/rush.rb

@@ -1,18 +1,40 @@
 class Blitz
-module Curl 
+module Curl # :nodoc:
+# Use this to run a rush (a load test) against your app. The return values
+# include the entire timeline containing the average duration, the concurrency,
+# the bytes sent/received, etc.
 class Rush
+    # Snapshot of a rush at time[i] containing information about hits, errors
+    # timeouts, etc.
     class Point
+        # The timestamp of this snapshot
         attr_reader :timestamp
+        
+        # The average response time at this time
         attr_reader :duration
+        
+        # The total number of hits that were generated
         attr_reader :total
+        
+        # The number of successful hits
         attr_reader :hits
+        
+        # The number of errors
         attr_reader :errors
+        
+        # The number of timeouts
         attr_reader :timeouts
+        
+        # The concurrency level at this time
         attr_reader :volume
+        
+        # The total number of bytes sent
         attr_reader :txbytes
+        
+        # The total number of bytes received
         attr_reader :rxbytes
         
-        def initialize json
+        def initialize json # :nodoc:
             @timestamp = json['timestamp']
             @duration = json['duration']
             @total = json['total']
@@ -25,19 +47,49 @@ class Rush
         end
     end
     
+    # Represents the results returned by the rush. Contains the entire timeline
+    # of snapshot values from the rush as well as the region from which the
+    # rush was executed.
     class Result
+        # The region from which the rush was executed
         attr_reader :region
+        
+        # The timeline of the rush containing various statistics.
         attr_reader :timeline
         
-        def initialize json
+        def initialize json # :nodoc:
             result = json['result']
             @region = result['region']
             @timeline = result['timeline'].map { |p| Point.new p }
         end        
     end
     
-    def self.execute args
-        if not args.member? 'pattern'
+    # Primary method for running a rush. The args is very similar to what
+    # the Sprint.execute method accepts, except this should also contain
+    # the pattern. If a block is given, it's invoked periodically with the
+    # partial results of the run (to report progress, perhaps)
+    #
+    #  args = { 
+    #      :url => 'http://www.mudynamics.com',
+    #      :headers => [ 'X-API-Token: foo' ],
+    #      :region => 'california',
+    #      :pattern => {
+    #          :intervals => [{ :start => 1, :end => 10000, :duration => 60 }]
+    #      }
+    #  }
+    #
+    #  result = Blitz::Curl::Sprint.execute args do |partial|
+    #      pp [ partial.region, partial.timeline.last.hits ]
+    #  end
+    #
+    # You can easily export the result to JSON, XML or compute the various 
+    # rates, etc.
+    def self.execute args, &block # |result|
+        self.queue(args).result &block
+    end
+    
+    def self.queue args # :nodoc:
+        if not args.member? 'pattern' and not args.member? :pattern
             raise ArgumentError, 'missing pattern'
         end
 
@@ -46,15 +98,15 @@ class Rush
         return self.new res
     end
     
-    attr_reader :job_id
-    attr_reader :region
+    attr_reader :job_id # :nodoc:
+    attr_reader :region # :nodoc:
     
-    def initialize json
+    def initialize json # :nodoc:
         @job_id = json['job_id']
         @region = json['region']
     end
     
-    def result
+    def result &block # :nodoc:
         last = nil
         while true
             sleep 2.0
@@ -83,7 +135,7 @@ class Rush
             
             last = Result.new(job)
             continue = yield last rescue false
-            if not continue
+            if continue == false
                 abort!
                 break
             end
@@ -94,7 +146,7 @@ class Rush
         return last
     end
     
-    def abort!
+    def abort! # :nodoc:
         Command::API.client.abort_job job_id rescue nil
     end    
 end

data/lib/blitz/curl/sprint.rb

@@ -1,14 +1,28 @@
 class Blitz
-module Curl 
+module Curl # :nodoc:
+# Use this to run a sprint against your app. The return values include the response
+# time, the region from which the sprint was run along with the full request
+# and response headers and the response body.
 class Sprint
+    # Represents the request object generated by the sprint. Contains all
+    # of the headers and POST/PUT data, if any.
     class Request
+        # The entire request line (GET / HTTP/1.1, for example)
         attr_reader :line
+        
+        # The method used in the request
         attr_reader :method
+        
+        # The URL, including path, query arguments and hash fragments
         attr_reader :url
+        
+        # All of the request headers (as a Hash of name/value pairs)
         attr_reader :headers
+        
+        # POST/PUT content, if any
         attr_reader :content
         
-        def initialize json
+        def initialize json # :nodoc:
             @line = json['line']
             @method = json['method']
             @url = json['url']
@@ -17,14 +31,25 @@ class Sprint
         end
     end
     
+    # Represents the response object generated by the sprint. Contains all
+    # of the headers and the response payload, if any.
     class Response
+        # The entire response line (HTTP/1.1 200 Okay, for example)
         attr_reader :line
+        
+        # The response status
         attr_reader :status
+        
+        # The message in the response line
         attr_reader :message
+        
+        # All of the response headers (as a Hash of name/value pairs)
         attr_reader :headers
+        
+        # The response content, if any
         attr_reader :content
         
-        def initialize json
+        def initialize json # :nodoc:
             @line = json['line']
             @status = json['status']
             @message = json['message']
@@ -33,14 +58,24 @@ class Sprint
         end        
     end
     
+    # Contains the result from a successful sprint
     class Result
+        # The region from which this sprint was executed
         attr_reader :region
+        
+        # The overall response time for the successful hit
         attr_reader :duration
+        
+        # The time it took for the TCP connection
         attr_reader :connect
+        
+        # The request object containing the URL, headers and content, if any
         attr_reader :request
+        
+        # The response object containing the status code, headers and content, if any
         attr_reader :response
         
-        def initialize json
+        def initialize json # :nodoc:
             result = json['result']
             @region = result['region']
             @duration = result['duration']
@@ -50,21 +85,36 @@ class Sprint
         end        
     end
     
+    # The primary method to execute a sprint from region. This method supports
+    # all of the arguments that the blitz bar supports. For example:
+    #
+    #  args = { 
+    #      :url => 'http://www.mudynamics.com',
+    #      :headers => [ 'X-API-Token: foo' ],
+    #      :region => 'california'
+    #  }
+    #
+    #  result = Blitz::Curl::Sprint.execute args
     def self.execute args
+        self.queue(args).result
+    end
+    
+    def self.queue args # :nodoc:
         args.delete 'pattern'
+        args.delete :pattern
 
         res = Command::API.client.curl_execute args
         raise Error.new(res) if res['error']
         return self.new res['job_id']
     end
     
-    attr_reader :job_id
+    attr_reader :job_id # :nodoc:
     
-    def initialize job_id
+    def initialize job_id # :nodoc:
         @job_id = job_id
     end
     
-    def result
+    def result # :nodoc:
         while true
             sleep 2.0
 
@@ -100,7 +150,7 @@ class Sprint
         end
     end
     
-    def abort
+    def abort # :nodoc:
         Command::API.client.abort_job job_id rescue nil
     end    
 end

data/lib/blitz/helper.rb

@@ -1,5 +1,5 @@
 class Blitz
-module Helper
+module Helper # :nodoc:
     def error msg
         $stderr.puts "!! #{msg}"
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: blitz
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 23
   prerelease: false
   segments: 
   - 0
   - 1
-  - 5
-  version: 0.1.5
+  - 6
+  version: 0.1.6
 platform: ruby
 authors: 
 - pcapr
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-18 00:00:00 -07:00
+date: 2011-04-20 00:00:00 -07:00
 default_executable: blitz
 dependencies: 
 - !ruby/object:Gem::Dependency