right_support 0.8.0 → 0.9.3

data/README.rdoc

@@ -1,13 +1,16 @@
-RightSupport is a library of reusable, unit-tested Ruby code that RightScale has found broadly useful.
+RightSupport is a library of reusable, unit- and functional-tested Ruby code that RightScale has found broadly useful.
 
 == What Does It Do?
 
 === Logging
 
 SystemLogger is a rewrite of the seattle.rb SyslogLogger class that features the following improvements:
- * Contains several bugfixes vs. SyslogLogger 1.4.0
- * Inherits from standard Ruby Logger class for guaranteed compatibility
- * Can be configured with options about how to handle newlines, ANSI escape codes, etc
+* Contains several bugfixes vs. SyslogLogger 1.4.0
+* Inherits from standard Ruby Logger class for guaranteed compatibility
+* Can be configured with options about how to handle newlines, ANSI escape codes, etc
+
+It is very similar to SystemLogger, with a few differences (e.g. it is a child class of Logger instead of
+merely being duck-type compatible). You use it as follows.
 
   @logger = SystemLogger.new('my_cool_app', :split=>true, :color=>false)
   @logger.info "Hello world\nThis will appear on separate lines\nand without \e[33;0mbeautiful colors" 
@@ -28,9 +31,19 @@ your web app's models before saving, check for preconditions in your controllers
 so forth.
 
 You can use it as a mixin by including the appropriate child module of
-RightSupport::Validation, but you really don't want to do that, do you? Instead, you
-want to call the module methods of RightSupport::Validation, which contains all of
-the same mixin methods.
+RightSupport::Validation.
+
+  class AwesomenessGenerator < ActiveRecord::Base
+    include RightSupport::Validation::OpenSSL
+
+    before_save do |record|
+      errors[:foo] = 'Hey, that's not a key!' unless pem_public_key?(record.foo)
+    end
+  end
+
+But you really don't want to do that, do you? Instead, you want to call the module
+methods of RightSupport::Validation, which contains all of the same mixin methods,
+but does not pollute the dispatch table of your application classes.
 
   the_key = STDIN.read
   raise ArgumentError unless RightSupport::Validation.ssh_public_key?(the_key)
@@ -48,19 +61,21 @@ which lets you perform easy client-side load balancing:
   end
 
 The balancer will keep trying requests until one of them succeeds without throwing
-any exceptions. (NB: a nil return value counts as success!!)
+any exceptions. (NB: a nil return value counts as success!!) If you specify that a
+certain class of exception is "fatal," then that exception will cause REST to re-
+raise immediately
 
 == HTTP REST Client
 
- We provide a very thin wrapper around the rest-client gem that enables simple but
- robust rest requests with a timeout, headers, etc. 
+We provide a very thin wrapper around the rest-client gem that enables simple but
+robust rest requests with a timeout, headers, etc.
 
- The RightSupport::Net::REST module is interface-compatible with the RestClient
- module, but allows an optional timeout to be specified as an extra parameter.
+The RightSupport::Net::REST module is interface-compatible with the RestClient
+module, but allows an optional timeout to be specified as an extra parameter.
 
    # Default timeout is 5 seconds
    RightSupport::Net::REST.get('http://localhost')
 
    # Make sure the REST request fails after 1 second so we can report an error
    # and move on!
-   RightSupport::Net::REST.get('http://localhost', {'X-Hello'=>'hi!'}, 1)
+   RightSupport::Net::REST.get('http://localhost', {'X-Hello'=>'hi!'}, 1)

data/lib/right_support/net/request_balancer.rb

@@ -1,5 +1,7 @@
 module RightSupport::Net
-  class NoResponse < Exception; end
+  # Raised to indicate the (uncommon) error condition where a RequestBalancer rotated
+  # through EVERY URL in a list without getting a non-nil, non-timeout response. 
+  class NoResult < Exception; end
 
   # Utility class that allows network requests to be randomly distributed across
   # a set of network endpoints. Generally used for REST requests by passing an
@@ -9,38 +11,143 @@ module RightSupport::Net
   # class usable for various network protocols, and potentially even for non-
   # networking purposes. The block does all the work; the balancer merely selects
   # a random request endpoint to pass to the block.
+  #
+  # PLEASE NOTE that the request balancer has a rather dumb notion of what is considered
+  # a "fatal" error for purposes of being able to retry; by default, it will consider
+  # any StandardError or any RestClient::Exception whose code is between 400-499. This
+  # MAY NOT BE SUFFICIENT for some uses of the request balancer! Please use the :fatal
+  # option if you need different behavior.
   class RequestBalancer
+    DEFAULT_FATAL_EXCEPTIONS = [ScriptError, ArgumentError, IndexError, LocalJumpError, NameError]
+
+    DEFAULT_FATAL_PROC = lambda do |e|
+      if DEFAULT_FATAL_EXCEPTIONS.any? { |c| e.is_a?(c) }
+        #Some Ruby builtin exceptions indicate program errors
+        true
+      elsif e.respond_to?(:http_code) && (e.http_code != nil)
+        #RestClient's exceptions all respond to http_code, allowing us
+        #to decide based on the HTTP response code.
+        #Any HTTP 4xx code EXCEPT 408 (Request Timeout) counts as fatal.
+        (e.http_code >= 400 && e.http_code < 500) && (e.http_code != 408)
+      else
+        #Anything else counts as non-fatal
+        false
+      end
+    end
+
+    DEFAULT_OPTIONS = {
+        :fatal        => DEFAULT_FATAL_PROC,
+        :on_exception => nil
+    }
+
     def self.request(endpoints, options={}, &block)
       new(endpoints, options).request(&block)
     end
 
+    # Constructor. Accepts a sequence of request endpoints which it shuffles randomly at
+    # creation time; however, the ordering of the endpoints does not change thereafter
+    # and the sequence is tried from the beginning for every request.
+    #
+    # === Parameters
+    # endpoints(Array):: a set of network endpoints (e.g. HTTP URLs) to be load-balanced
+    #
+    # === Options
+    # fatal(Class):: a class, list of classes or decision Proc to determine whether an exception is fatal and should not be retried
+    # on_exception(Proc|Lambda):: notification hook that accepts three arguments: whether the exception is fatal, the exception itself, and the endpoint for which the exception happened
+    #
     def initialize(endpoints, options={})
-      raise ArgumentError, "Must specify at least one endpoint" unless endpoints && !endpoints.empty?
+      @options = DEFAULT_OPTIONS.merge(options)
+
+      unless endpoints && !endpoints.empty?
+        raise ArgumentError, "Must specify at least one endpoint"
+      end
+
+      unless test_callable_arity(options[:fatal], 1, true)
+        raise ArgumentError, ":fatal callback must accept one parameter"
+      end
+
+      unless test_callable_arity(options[:on_exception], 3, false)
+        raise ArgumentError, ":on_exception callback must accept three parameters"
+      end
+
       @endpoints = endpoints.shuffle
-      @options = options.dup
     end
 
+    # Perform a request.
+    #
+    # === Block
+    # This method requires a block, to which it yields in order to perform the actual network
+    # request. If the block raises an exception or provides nil, the balancer proceeds to try
+    # the next URL in the list.
+    #
+    # === Raise
+    # ArgumentError:: if a block isn't supplied
+    # NoResult:: if *every* URL in the list times out or returns nil
+    #
+    # === Return
+    # Return the first non-nil value provided by the block.
     def request
       raise ArgumentError, "Must call this method with a block" unless block_given?
 
-      exception = nil
-      result    = nil
+      exceptions = []
+      result     = nil
+      success    = false
 
-      @endpoints.each do |host|
+      @endpoints.each do |endpoint|
         begin
-          result = yield(host)
-          break unless result.nil?
+          result  = yield(endpoint)
+          success = true
+          break
         rescue Exception => e
-          fatal = @options[:fatal]
-          safe  = @options[:safe]
-          raise e if (fatal && e.kind_of?(fatal)) && !(safe && e.kind_of?(safe))
-          exception = e
+          if to_raise = handle_exception(endpoint, e)
+            raise(to_raise)
+          else
+            exceptions << e
+          end
         end
       end
 
-      return result if result
-      raise exception if exception
-      raise NoResponse, "Tried all URLs with neither result nor exception!"
+      return result if success
+
+      exceptions = exceptions.map { |e| e.class.name }.uniq.join(', ')
+      raise NoResult, "All URLs in the rotation failed! Exceptions: #{exceptions}"
+    end
+
+    protected
+
+    # Decide what to do with an exception. The decision is influenced by the :fatal
+    # option passed to the constructor.
+    def handle_exception(endpoint, e)
+      fatal = @options[:fatal] || DEFAULT_FATAL_PROC
+
+      #The option may be a proc or lambda; call it to get input
+      fatal = fatal.call(e) if fatal.respond_to?(:call)
+
+      #The options may be single exception classes, in which case we want to expand
+      #it out into a list
+      fatal = [fatal] if fatal.is_a?(Class)
+
+      #The option may be a list of exception classes, in which case we want to evaluate
+      #whether the exception we're handling is an instance of any mentioned exception
+      #class
+      fatal = fatal.any?{ |c| e.is_a?(c) } if fatal.respond_to?(:any?)
+
+      @options[:on_exception].call(fatal, e, endpoint) if @options[:on_exception]
+
+      if fatal
+        #Final decision: did we identify it as fatal?
+        return e
+      else
+        return nil
+      end
+    end
+
+    # Test that something is a callable (Proc, Lambda or similar) with the expected arity.
+    # Used mainly by the initializer to test for correct options.
+    def test_callable_arity(callable, arity, optional)
+      return true if callable.nil?
+      return true if optional && !callable.respond_to?(:call)
+      return callable.respond_to?(:arity) && (callable.arity == arity)
     end
   end # RequestBalancer
 

data/lib/right_support/net/rest.rb

@@ -1,36 +1,83 @@
 module RightSupport::Net
+  begin
+    require 'right_http_connection' 
+  rescue LoadError
+  end
   if_require_succeeds('restclient') do
     HAS_REST_CLIENT = true
   end
 
+  # Raised to indicate that no suitable provider of REST/HTTP services was found. Since RightSupport's
+  # REST support is merely a wrapper around other libraries, it cannot work in isolation. See the REST
+  # module for more information about supported providers.
   class NoProvider < Exception; end
 
   #
-  # A wrapper for the rest-client gem that provides timeouts and other
-  # useful features while preserving the simplicity and ease of use of
-  # RestClient's simple, static (module-level) interface.
+  # A wrapper for the rest-client gem that provides timeouts and other useful features while preserving
+  # the simplicity and ease of use of RestClient's simple, static (module-level) interface.
+  #
+  # Even though this code relies on RestClient, the right_support gem does not depend on the rest-client
+  # gem because not all users of right_support will want to make use of this interface. If one of REST's
+  # method is called and RestClient is not available, an exception will be raised.
+  #
+  #
+  # This module supports a subset of the module methods provided by RestClient and is interface-compatible
+  # with those methods it replaces; the only difference is that the REST version of each method accepts an
+  # additional, optional parameter which is a request timeout in seconds. The RestClient gem does not allow
+  # timeouts without instantiating a "heavyweight" REST client object.
+  #
+  #   # GET
+  #   xml = REST.get 'http://example.com/resource'
+  #   # and, with timeout of 5 seconds...
+  #   jpg = REST.get 'http://example.com/resource', :accept => 'image/jpg', 5
+  #
+  #   # authentication and SSL
+  #   REST.get 'https://user:password@example.com/private/resource'
   #
+  #   # POST or PUT with a hash sends parameters as a urlencoded form body
+  #   REST.post 'http://example.com/resource', :param1 => 'one'
+  #
+  #   # nest hash parameters, add a timeout of 10 seconds (and specify "no extra headers")
+  #   REST.post 'http://example.com/resource', :nested => { :param1 => 'one' }, {}, 10
+  #
+  #   # POST and PUT with raw payloads
+  #   REST.post 'http://example.com/resource', 'the post body', :content_type => 'text/plain'
+  #   REST.post 'http://example.com/resource.xml', xml_doc
+  #   REST.put 'http://example.com/resource.pdf', File.read('my.pdf'), :content_type => 'application/pdf'
+  #
+  #   # DELETE
+  #   REST.delete 'http://example.com/resource'
+  #
+  #   # retrieve the response http code and headers
+  #   res = REST.get 'http://example.com/some.jpg'
+  #   res.code                    # => 200
+  #   res.headers[:content_type]  # => 'image/jpg'
   module REST
     DEFAULT_TIMEOUT = 5
-    
+
+    # Wrapper around RestClient.get -- see class documentation for details.
     def self.get(url, headers={}, timeout=DEFAULT_TIMEOUT, &block)
       request(:method=>:get, :url=>url, :timeout=>timeout, :headers=>headers, &block)
     end
 
+    # Wrapper around RestClient.get -- see class documentation for details.
     def self.post(url, payload, headers={}, timeout=DEFAULT_TIMEOUT, &block)
       request(:method=>:post, :url=>url, :payload=>payload,
               :timeout=>timeout, :headers=>headers, &block)
     end
 
+    # Wrapper around RestClient.get -- see class documentation for details.
     def self.put(url, payload, headers={}, timeout=DEFAULT_TIMEOUT, &block)
       request(:method=>:put, :url=>url, :payload=>payload,
               :timeout=>timeout, :headers=>headers, &block)
     end
 
+    # Wrapper around RestClient.get -- see class documentation for details.
     def self.delete(url, headers={}, timeout=DEFAULT_TIMEOUT, &block)
       request(:method=>:delete, :url=>url, :timeout=>timeout, :headers=>headers, &block)
     end
 
+    # Wrapper around RestClient::Request.execute -- see class documentation for details.
     def self.request(options, &block)
       if HAS_REST_CLIENT
         RestClient::Request.execute(options, &block)

data/lib/right_support/system_logger.rb

@@ -54,9 +54,9 @@ module RightSupport
       # options(Hash):: (optional) configuration options to use, see below
       #
       # === Options
-      # :facility:: the syslog facility to use for messages, 'local0' by default
-      # :split(true|false):: if true, splits multi-line messages into separate syslog entries
-      # :color(true|false):: if true, passes ANSI escape sequences through to syslog
+      # facility:: the syslog facility to use for messages, 'local0' by default
+      # split(true|false):: if true, splits multi-line messages into separate syslog entries
+      # color(true|false):: if true, passes ANSI escape sequences through to syslog
       #
       def initialize(program_name='ruby', options={})
         @options = DEFAULT_OPTIONS.merge(options)
@@ -65,6 +65,8 @@ module RightSupport
         facility = options[:facility] || 'local0'
         fac_map = {'user'=>8}
         (0..7).each { |i| fac_map['local'+i.to_s] = 128+8*i }
+
+        @@syslog.close if @@syslog && @@syslog.opened?
         @@syslog ||= Syslog.open(program_name, nil, fac_map[facility.to_s])
       end
 

data/right_support.gemspec

@@ -7,8 +7,8 @@ spec = Gem::Specification.new do |s|
   s.required_ruby_version = Gem::Requirement.new(">= 1.8.7")
 
   s.name    = 'right_support'
-  s.version = '0.8.0'
-  s.date    = '2011-04-09'
+  s.version = '0.9.3'
+  s.date    = '2011-05-13'
 
   s.authors = ['Tony Spataro']
   s.email   = 'tony@rightscale.com'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: right_support
 version: !ruby/object:Gem::Version 
-  hash: 63
+  hash: 61
   prerelease: false
   segments: 
   - 0
-  - 8
-  - 0
-  version: 0.8.0
+  - 9
+  - 3
+  version: 0.9.3
 platform: ruby
 authors: 
 - Tony Spataro
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-09 00:00:00 -07:00
+date: 2011-05-13 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency