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

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" 

CustomLogger is a Rack middleware that allows a Rack app to use any log sink it wishes. The
stock Rack logger middleware is inflexible and gives the end user no control over which logger is used
or where the log entries go.

  require 'right_support/rack/custom_logger'

  my_logger = MyAwesomeLogger.new
  use RightSupport::Rack::CustomLogger, Logger::INFO, my_logger

== Input Validation

The Validation module contains several format-checkers that can be used to validate
your web app's models before saving, check for preconditions in your controllers, and
so forth.

You can use it as a mixin by including the appropriate child module of
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)

== Request Balancing

The RequestBalancer class will randomly choose endpoints for a network request,
which lets you perform easy client-side load balancing:

  include RightSupport::Net

  urls = ['http://localhost', 'http://otherhost']
  RequestBalancer.request(urls, :fatal=>RestClient::ResourceNotFound) do |url|
    REST.get(url)
  end

The balancer will keep trying requests until one of them succeeds without throwing
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.

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)