kbrown / egregious Goto Github PK

Egregious is a rails based exception handling gem for well defined http exception handling for json, xml and html.

If you have a json or xml api into your rails application, you probably have added your own exception handling to map
exceptions to a http status and formatting your json and xml output.  We decided to create egregious. One of the goals
is to start providing a more consistent api error experience for all rails applications. As of the creation of
egregious the behavior of rails was to return html when an exception is thrown with the status code of 500.  With
egregious proper json and html of the error will be returned with a good default mapping of exceptions to http status
codes.  This allows api developers to respond to the status code properly, instead of scratching their head with 500's
coming back all the time. If the problem was the api caller then the result codes are in the 300 range. If the problem
was on the server then the status codes are in the 500 range.  The returned exception message and exception type
provide the caller context information.

 What egregious can do:

 * Defines default exception handling for most common ruby, rails, warden and cancan exceptions.
   (warden and cancan are optional)
 * Catches defined exceptions using a rescue_with returning the status code defined for each exception
   and well structured json, xml
 * For html production requests attempts to load the html error pages for the mapped status code,
   falling back to the 500.html page.
 * Defines exceptions for all http status codes allowing you to throw these exceptions anywhere in your code.
 * Allows you to change the exception mapping to fit your needs, adding exceptions and changing status mapping.
 * If Hoptoad is defined it will send the errors to Hoptoad/Airbrake.
 * The error will be logged with stack trace


REQUIRES:
  Rails 3.x

USAGE:
1) Add to your Gemfile:
gem 'egregious'

2) In your ApplicationController add:
include Egregious

Optionally, to configure create an initializer and add:

Egregious.exception_codes.merge!({NameError => :bad_request})

This will either add a new mapping or replace the existing mapping to a new status code.
You can pass the status code as a symbol, integer or string.

In your code if you want to send an error back just throw an exception. For example:

raise Egregious::BadRequest.new("You can not created an order without a customer.") unless customer_id

All the http status codes have exception classes named after them in the Egregious module. You can throw any exception,
or define your own exceptions. You can find a list in the Rack::Utils::HTTP_STATUS_CODES class.

If you want to change the behavior then you can override the following methods in your ApplicationController.

# override this if you want your flash to behave differently
def egregious_flash(exception)
    flash.now[:alert] = exception.message
end

# override this if you want your logging to behave differently
def egregious_log(exception)
    logger.fatal(
        "\n\n" + exception.class.to_s + ' (' + exception.message.to_s + '):\n    ' +
            clean_backtrace(exception).join("\n    ") +
            "\n\n")
    HoptoadNotifier.notify(exception) if defined?(HoptoadNotifier)
end

# override this if you want to change your respond_to behavior
def egregious_respond_to(exception)
    respond_to do |format|
          status = status_code_for_exception(exception)
          format.xml { render :xml=> exception.to_xml, :status => status }
          format.json { render :json=> exception.to_json, :status => status }
          # render the html page for the status we are returning it exists...if not then render the 500.html page.
          format.html { render :file => File.exists?(build_html_file_path(status)) ?
                                          build_html_file_path(status) : build_html_file_path('500')}
    end
end

# override this if you want to change what html static file gets returned.
def build_html_file_path(status)
    File.expand_path(Rails.root, 'public', status + '.html')
  end