wrangler 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+# Copyright (c) 2009 Umamibud, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,247 @@
+= Wrangler
+
+== NOTE/DISCLAIMER
+This gem is almost completely inspired by/ripped off the exception_notification
+plugin/gem, but had to hack too much to get things to work with delayed_job
+that I just decided to start from scratch. You'll see that much has been
+borrowed however, so I owe a huge debt to the originals (exception_notification
+[http://github.com/rails/exception_notification] and
+super_exception_notification [http://github.com/pboling/exception_notification])
+to help me recreate the Rails hacking.
+
+If you don't really care about using delayed_job for your emailing, consider
+going back to the originals, as they're likely better maintained.... ;)
+
+== Overview:
+A gem for handling exceptions in a Rails application/environment. 
+
+Some highlights:
+* Allows for rendering error pages and sending email notifications in case of
+errors.
+* Allows for lots of configuring of which pages to show, whether to email or not.
+* Allows for asynchronous emailing through delayed_job if available, but works
+fine even if delayed_job not installed (email will be synchronous however)
+* Will honor filter_parameters set in the controller including the Wrangler
+module (except if the parameters are in the URL for GETs) when logging and
+emailing application state at the time of the exception
+* Allows email notification on exceptions thrown totally outside Controller
+context, e.g. in a script run (with rails environment) in a cronjob or
+delayed_job
+
+== Quickstart
+=== Bare Minimum
+There are a lot of defaults set, so getting started should be pretty easy. In
+fact, if you don't want any email notifications, you basically just need to
+include the Wrangler module in your controller:
+    # application_controller.rb
+    class ApplicationController < ActionController::Base
+      include Wrangler
+
+      ...
+    end
+
+=== Enabling email notifications
+Email notifications are configured to be sent with the default configuration,
+but you'll need to specify from and to addresses for emails to actually be sent.
+So that brings us to the configuration of Wrangler. Recommended: just create a
+new initializer file (create a wrangler.rb (or whatever you want to name the file)
+in  RAILS_ROOT/config/initializers/wrangler.rb). In it, add the following:
+
+  Wrangler::ExceptionNotifier.configure do |notifier_config|
+    notifier_config.merge! :from_address => 'monitor@umamibud.com',
+                           :recipient_addresses => ['u-ops-monitor@umamibud.com']
+  end
+
+And, if you haven't already configured ActionMailer to send emails, you'll need
+to do that (e.g. setting ActionMailer::Base.smtp_settings), and even after you
+have, you may want to change some settings in order to send from a different
+account from the one you may use to email your users (e.g. change the :user_name
+for smtp_settings):
+
+  Wrangler::ExceptionNotifier.smtp_settings.merge! :user_name => 'notifier@mydomain.com'
+
+(Recommend just putting that in the same wrangler.rb initializer you created above)
+
+For more info on smtp_settings, see ActionMailer (http://am.rubyonrails.org/)
+
+== Configuration
+There are two different classes that receive configuration, ExceptionHandler and
+ExceptionNotifier.
+
+ExceptionHandler stores configurations about what to do about exceptions (whether to
+handle them, email them, which error templates to render for each exception...).
+
+ExceptionNotifier handles the sending of emails when exceptions occur, so
+stores configurations about where to send the emails.
+
+You override defaults on each using the same syntax (as seen above) by calling the
+configure() method on the class and using the config hash that is yielded to
+set your configurations. See the method documentation for the configure() methods
+themselves, but here's the basic idea:
+
+     Wrangler::ExceptionHandler.configure do |handler_config|
+       handler_config[:key1] = value1
+       handler_config[:key2] = value2
+       handler_config[:key_for_a_hash].merge! :subkey => value
+       handler_config[:key_for_an_array] << another_value
+     end
+    
+     OR
+    
+     Wrangler::ExceptionHandler.configure do |handler_config|
+       handler_config.merge! :key1 => value1,
+                             :key2 => value2,
+       handler_config[:key_for_a_hash].merge! :subkey => value
+       handler_config[:key_for_an_array] << another_value
+     end
+
+(same with Wrangler::ExceptionNotifier, except different classname)
+
+Most configurations are single values (e.g. nums or strings),
+but some are hashes or arrays. You can either overwrite the hashes/arrays, or
+selectively delete, or just append. Recommend just appending to the defaults
+in most cases, but if you know what you're doing, you can do whatever you like!
+
+Here is the full set of configuration values for both classes, as well as their
+default values (pasted in from the classes, so you can check the code directly
+to make sure you've got the latest! :) ):
+
+   ####################
+   # ExceptionHandler:
+   ####################
+
+      :app_name => '',
+      :handle_local_errors => false,
+      :handle_public_errors => true,
+      # send email for local reqeusts. ignored if :handle_local_errors false
+      :notify_on_local_error => false,
+      # send email for public requests. ignored if :handle_public_errors false
+      :notify_on_public_error => true,
+      # send email for exceptions caught outside of a controller context
+      :notify_on_background_error => true,
+      # configure whether to send emails synchronously or asynchronously
+      # using delayed_job (these can be true even if delayed job is not
+      # installed, in which case, will just send emails synchronously anyway)
+      :delayed_job_for_controller_errors => false,
+      :delayed_job_for_non_controller_errors => false,
+      # mappings from exception classes to http status codes (see above)
+      # add/remove from this list as desired in environment configuration
+      :error_class_status_codes => Wrangler::codes_for_exception_classes,
+      # explicitly indicate which exceptions to send email notifications for
+      :notify_exception_classes => %w(),
+      # indicate which http status codes should result in email notification
+      :notify_status_codes => %w( 405 500 503 ),
+      # where to look for app-specific error page templates (ones you create
+      # yourself, for example...there are some defaults in this gem you can
+      # use as well...and that are configured already by default)
+      :error_template_dir => File.join(RAILS_ROOT, 'app', 'views', 'error'),
+      # excplicit mappings from exception class to arbitrary error page
+      # templates, different set for html and js responses (Wrangler determines
+      # which to use automatically, so you can have an entry in both
+      # hashes for the same error class)
+      :error_class_html_templates => {},
+      :error_class_js_templates => {},
+      # you can specify a fallback failsafe error template to render if
+      # no appropriate template is found in the usual places (you shouldn't
+      # rely on this, and error messages will be logged if this template is
+      # used). note: there's an even more failsafe template included in the
+      # gem (absolute_last_resort...) below, but DON'T CHANGE IT!!!
+      :default_error_template => '',
+      # these filter out any HTTP params that are undesired
+      :request_env_to_skip => [ /^rack\./,
+                                "action_controller.rescue.request",
+                                "action_controller.rescue.response" ],
+      # mapping from exception classes to templates (if desired), express
+      # in absolute paths. use wildcards like on cmd line (glob-like), NOT
+      # regexp-style
+
+      # just DON'T change this! this is the error template of last resort!
+      :absolute_last_resort_default_error_template =>
+        File.join(WRANGLER_ROOT,'rails','app','views','wrangler','500.html')
+
+   #####################
+   # ExceptionNotifier:
+   #####################
+
+      # who the emails will be coming from. if nil or missing or empty string,
+      # effectively disables email notification
+      :from_address => '',
+      # array of addresses that the emails will be sent to. if nil or missing
+      # or empty array, effectively disables email notification.
+      :recipient_addresses => [],
+      # what will show up at the beginning of the subject line for each email
+      # sent note: will be preceded by "[<app_name (if any)>...", where app_name
+      # is the :app_name config value from ExceptionHandler (or explicit
+      # proc_name given to notify_on_error() method)
+      :subject_prefix => "#{(defined?(Rails) ? Rails.env : RAILS_ENV).capitalize} ERROR",
+      # can use this to define app-specific mail views using the same data
+      # made available in exception_notification()
+      :mailer_template_root => File.join(WRANGLER_ROOT, 'views')
+
+== Search algorithm for error templates (given an exception and a status_code):
+When trying to find an appropriate error page template to render, Wrangler
+goes through several different attempts to locate an appropriate template,
+beginning with templates you've explicitly associated with the exception class
+or status code that has arisen...and on through to assuming default file naming
+conventions and finally failsafe default templates.
+
+# if there is an explicit mapping from the exception to an error page in
+:error_class_xxx_templates, use that
+# if there is a mapping in :error_class_templates for which the exception
+returns true to an is_a? call, use that
+# if there is a file/template corresponding to the exception name
+(underscorified) in one of the following locations, use that:
+** config[:error_template_dir]/
+** RAILS_ROOT/public/
+** WRANGLER_ROOT/rails/app/views/wrangler/
+# if there is a file/template corresponding to the status code
+(e.g. named ###.html.erb where ### is the status code) in one of the following
+locations, use that:
+** config[:error_template_dir]/
+** RAILS_ROOT/public/
+** WRANGLER_ROOT/rails/app/views/wrangler/
+# if there is a file/template corresponding to a parent class name of the
+exception (underscorified) one of the following locations, use that:
+** config[:error_template_dir]/
+** RAILS_ROOT/public/
+** WRANGLER_ROOT/rails/app/views/wrangler/
+# :default_error_template
+# :absolute_last_resort_default_error_template
+
+== Using outside a Controller:
+You can still use Wrangler outside the context of a Controller class. If you'll
+be running within the context of an object instance, you can just include Wrangler
+in the object's class. If you'll be running 'static' code, you can refer to
+relevant methods via the Wrangler module. Note that in both cases, you'll be
+calling the notify_on_error() method. Also note that the notify_on_error()
+method will re-raise the exception that occurred in the block, so you may want
+to begin/rescue/end around the notify_on_error() method call
+
+using in an object instance:
+
+   class MyClass
+     include Wrangler
+
+     def my_error_method; raise "error!"; end
+     
+     def call_a_method
+       notify_on_error { my_error_method }
+     rescue => e
+       exit
+     end
+   end
+
+using 'statically':
+
+   Wrangler::notify_on_error { run_some_method_that_might_raise_exceptions }
+
+== Maintaining the Wrangler gem
+Should be pretty straightforward. Note that we're using jeweler, so the .gemspec
+isn't included in the git repos; it gets generated dynamically from the settings
+in Rakefile. 
+
+To build:
+
+     cd .../wrangler
+     rake gemspec
+     rake build

data/lib/wrangler/exception_handler.rb

@@ -0,0 +1,280 @@
+module Wrangler
+
+  # a utility method that should only be used internally. don't call this; it
+  # should only be called once by the Config class and you can get/set it there.
+  # returns a mapping from exception classes to http status codes
+  #-----------------------------------------------------------------------------
+  def self.codes_for_exception_classes
+    classes = {
+      # These are standard errors in rails / ruby
+      NameError =>      "503",
+      TypeError =>      "503",
+      RuntimeError =>   "500",
+      ArgumentError =>  "500",
+      # the default mapping for an unrecognized exception class
+      :default => "500"
+    }
+
+    # from exception_notification gem:
+    # Highly dependent on the verison of rails, so we're very protective about these'
+    classes.merge!({ ActionView::TemplateError => "500"})             if defined?(ActionView)       && ActionView.const_defined?(:TemplateError)
+    classes.merge!({ ActiveRecord::RecordNotFound => "400" })         if defined?(ActiveRecord)     && ActiveRecord.const_defined?(:RecordNotFound)
+    classes.merge!({ ActiveResource::ResourceNotFound => "404" })     if defined?(ActiveResource)   && ActiveResource.const_defined?(:ResourceNotFound)
+
+    # from exception_notification gem:
+    if defined?(ActionController)
+      classes.merge!({ ActionController::UnknownController => "404" })          if ActionController.const_defined?(:UnknownController)
+      classes.merge!({ ActionController::MissingTemplate => "404" })            if ActionController.const_defined?(:MissingTemplate)
+      classes.merge!({ ActionController::MethodNotAllowed => "405" })           if ActionController.const_defined?(:MethodNotAllowed)
+      classes.merge!({ ActionController::UnknownAction => "501" })              if ActionController.const_defined?(:UnknownAction)
+      classes.merge!({ ActionController::RoutingError => "404" })               if ActionController.const_defined?(:RoutingError)
+      classes.merge!({ ActionController::InvalidAuthenticityToken => "405" })   if ActionController.const_defined?(:InvalidAuthenticityToken)
+    end
+
+    return classes
+  end
+
+  # class that holds configuration for the exception handling logic. may also
+  # include a helper method or two, but the main interaction with
+  # ExceptionHandler is setting and getting config, e.g.
+  #
+  # Wrangler::ExceptionHandler.configure do |handler_config|
+  #   handler_config.merge! :key => value
+  # end
+  #-----------------------------------------------------------------------------
+  class ExceptionHandler
+
+    # the default configuration
+    @@config ||= {
+      :app_name => '',
+      :handle_local_errors => false,
+      :handle_public_errors => true,
+      # send email for local reqeusts. ignored if :handle_local_errors false
+      :notify_on_local_error => false,
+      # send email for public requests. ignored if :handle_public_errors false
+      :notify_on_public_error => true,
+      # send email for exceptions caught outside of a controller context
+      :notify_on_background_error => true,
+      # configure whether to send emails synchronously or asynchronously
+      # using delayed_job (these can be true even if delayed job is not
+      # installed, in which case, will just send emails synchronously anyway)
+      :delayed_job_for_controller_errors => false,
+      :delayed_job_for_non_controller_errors => false,
+      # mappings from exception classes to http status codes (see above)
+      # add/remove from this list as desired in environment configuration
+      :error_class_status_codes => Wrangler::codes_for_exception_classes,
+      # explicitly indicate which exceptions to send email notifications for
+      :notify_exception_classes => %w(),
+      # indicate which http status codes should result in email notification
+      :notify_status_codes => %w( 405 500 503 ),
+      # where to look for app-specific error page templates (ones you create
+      # yourself, for example...there are some defaults in this gem you can
+      # use as well...and that are configured already by default)
+      :error_template_dir => File.join(RAILS_ROOT, 'app', 'views', 'error'),
+      # excplicit mappings from exception class to arbitrary error page
+      # templates, different set for html and js responses (Wrangler determines
+      # which to use automatically, so you can have an entry in both
+      # hashes for the same error class)
+      :error_class_html_templates => {},
+      :error_class_js_templates => {},
+      # you can specify a fallback failsafe error template to render if
+      # no appropriate template is found in the usual places (you shouldn't
+      # rely on this, and error messages will be logged if this template is
+      # used). note: there's an even more failsafe template included in the
+      # gem (absolute_last_resort...) below, but DON'T CHANGE IT!!!
+      :default_error_template => '',
+      # these filter out any HTTP params that are undesired
+      :request_env_to_skip => [ /^rack\./,
+                                "action_controller.rescue.request",
+                                "action_controller.rescue.response" ],
+      # mapping from exception classes to templates (if desired), express
+      # in absolute paths. use wildcards like on cmd line (glob-like), NOT
+      # regexp-style
+
+      # just DON'T change this! this is the error template of last resort!
+      :absolute_last_resort_default_error_template =>
+        File.join(WRANGLER_ROOT,'rails','app','views','wrangler','500.html')
+    }
+
+    cattr_accessor :config
+
+    # allows for overriding default configuration settings.
+    # in your environment.rb or environments/<env name>.rb, use a block that
+    # accepts one argument
+    # * recommend against naming it 'config' as you will probably be calling it
+    #   within the config block in env.rb...):
+    # * note that some of the config values are arrays or hashes; you can
+    #   overwrite them completely, delete or insert/merge new entries into the
+    #   default values as you see fit...but in most cases, recommend AGAINST
+    #   overwriting the arrays/hashes completely unless you don't want to
+    #   take advantage of lots of out-of-the-box config
+    #
+    # Wrangler::ExceptionHandler.configure do |handler_config|
+    #   handler_config[:key1] = value1
+    #   handler_config[:key2] = value2
+    #   handler_config[:key_for_a_hash].merge! :subkey => value
+    #   handler_config[:key_for_an_array] << another_value
+    # end
+    #
+    # OR
+    #
+    # Wrangler::ExceptionHandler.configure do |handler_config|
+    #   handler_config.merge! :key1 => value1,
+    #                         :key2 => value2,
+    #   handler_config[:key_for_a_hash].merge! :subkey => value
+    #   handler_config[:key_for_an_array] << another_value
+    # end
+    # 
+    # NOTE: sure, you can change this configuration on the fly in your app, but
+    # we don't recommend it. plus, if you do and you're using delayed_job, there
+    # may end up being configuration differences between the rails process and
+    # the delayed_job process, resulting in unexpected behavior. so recommend
+    # you just modify this in the environment config files...or if you're doing
+    # something sneaky, you're on your own.
+    #-----------------------------------------------------------------------------
+    def self.configure(&block)
+      yield @@config
+    end
+
+
+    # translate the exception class to an http status code, using default
+    # code (set in config) if the exception class isn't excplicitly mapped
+    # to a status code in config
+    #---------------------------------------------------------------------------
+    def self.status_code_for_exception(exception)
+      if exception.respond_to?(:status_code)
+        return exception.status_code
+      else
+        return config[:error_class_status_codes][exception.class] ||
+               config[:error_class_status_codes][:default]
+      end
+    end
+
+  end # end ExceptionHandler class
+
+  ##############################################################################
+  # actual exception handling code
+  ##############################################################################
+
+  # make all of these instance methods also module functions
+  module_function
+
+  # execute the code block passed as an argument, and follow notification
+  # rules if an exception bubbles out of the block.
+  #
+  # return value:
+  #   * if an exception bubbles out of the block, the exception is re-raised to
+  #     calling code.
+  #   * otherwise, returns nil
+  #-----------------------------------------------------------------------------
+  def notify_on_error(proc_name = nil, &block)
+    begin
+      yield
+    rescue => exception
+      options = {}
+      options.merge! :proc_name => proc_name unless proc_name.nil?
+      handle_exception(exception, options)
+    end
+
+    return nil
+  end
+
+  # the main exception-handling method. decides whether to notify or not,
+  # whether to render an error page or not, and to make it happen.
+  #
+  # arguments:
+  #   - exception: the exception that was caught
+  #
+  # options:
+  #   :request: the request object (if any) that resulted in the exception
+  #   :render_errors: boolean indicating if an error page should be rendered
+  #                   or not (Rails only)
+  #   :proc_name: a string representation of the process/app that was running
+  #               when the exception was raised. default value is
+  #               Wrangler::ExceptionHandler.config[:app_name].
+  #-----------------------------------------------------------------------------
+  def handle_exception(exception, options = {})
+    request = options[:request]
+    render_errors = options[:render_errors] || false
+    proc_name = options[:proc_name] || config[:app_name]
+
+    status_code = Wrangler::ExceptionHandler.status_code_for_exception(exception)
+    request_data = request_data_from_request(request) unless request.nil?
+
+    if notify_on_exception?(exception, status_code)
+      if notify_with_delayed_job?
+        # don't pass in request as it contains not-easily-serializable stuff
+        Wrangler::ExceptionNotifier.send_later(:deliver_exception_notification,
+                                              exception,
+                                              proc_name,
+                                              exception.backtrace,
+                                              status_code,
+                                              request_data)
+      else
+        Wrangler::ExceptionNotifier.deliver_exception_notification(exception,
+                                                         proc_name,
+                                                         exception.backtrace,
+                                                         status_code,
+                                                         request_data,
+                                                         request)
+      end
+    end
+
+    log_exception(exception, request_data, status_code)
+
+    if render_errors
+      render_error_template(exception, status_code)
+    end
+  end
+
+
+  # determine if the app is configured to notify for the given exception or
+  # status code
+  #-----------------------------------------------------------------------------
+  def notify_on_exception?(exception, status_code = nil)
+    # first determine if we're configured to notify given the context of the
+    # exception
+    if self.respond_to?(:local_request?)
+      if (local_request? && config[:notify_on_local_error]) ||
+          (!local_request? && config[:notify_on_public_error])
+        notify = true
+      else
+        notify = false
+      end
+    else
+      notify = config[:notify_on_background_error]
+    end
+
+    # now if config says notify in this case, check if we're configured to
+    # notify for this exception or this status code
+    return notify &&
+      (config[:notify_exception_classes].include?(exception.class) ||
+       config[:notify_status_codes].include?(status_code))
+  end
+
+  # determine if email should be sent with delayed job or not (delayed job
+  # must be installed and config set to use delayed job
+  #-----------------------------------------------------------------------------
+  def notify_with_delayed_job?
+    use_dj = false
+
+    if self.is_a?(ActionController::Base)
+      if config[:delayed_job_for_controller_errors] &&
+          ExceptionNotifier.respond_to?(:send_later)
+        use_dj = true
+      else
+        use_dj = false
+      end
+    else
+      if config[:delayed_job_for_non_controller_errors] &&
+          ExceptionNotifier.respond_to?(:send_later)
+        use_dj = true
+      else
+        use_dj = false
+      end
+    end
+
+    return use_dj
+  end
+
+end