wrangler 0.1.0

data/lib/wrangler/exception_notifier.rb

@@ -0,0 +1,142 @@
+module Wrangler
+  # handles notifying (sending emails) for the wrangler gem. configuration for
+  # the class is set in an initializer via the configure() method, e.g.
+  #
+  # Wrangler::ExceptionNotifier.configure do |config|
+  #   config[:key] = value
+  # end
+  #
+  # see README or source code for possible values and default settings
+  #-----------------------------------------------------------------------------
+  class ExceptionNotifier < ActionMailer::Base
+    # the default configuration
+    @@config ||= {
+      # 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')
+    }
+
+    cattr_accessor :config
+
+    def self.configure(&block)
+      yield @@config
+    end
+
+    self.template_root = config[:mailer_template_root]
+
+    # form and send the notification email (note: this gets called indirectly
+    # when you call ExceptionNotifier.deliver_exception_notification())
+    #
+    # arguments:
+    #   - exception: the exception that was raised
+    #   - proc_name: the name of the process in which the exception arised
+    #   - backtrace: the stack trace from the exception (passing in excplicitly
+    #                because serializing the exception does not preserve the
+    #                backtrace (in case delayed_job is used to async the email)
+    #   - status_code: the (string) http status code that the exception has been
+    #                  mapped to. Optional, but no default is provided, so
+    #                  no status code info will be contained in the email.
+    #   - request_data: hash with relevant data from the request object.
+    #                   Optional, but if not present, then assumed the exception
+    #                   was not due to an http request and thus no request
+    #                   data will be contained in the email.
+    #   - request: the original request that resulted in the exception. may
+    #              be nil and MUST be nil if calling this method with
+    #              delayed_job. Optional.
+    #---------------------------------------------------------------------------
+    def exception_notification(exception, proc_name, backtrace,
+                               status_code = nil,
+                               request_data = nil,
+                               request = nil)
+
+      # don't try to send email if there are no from or recipient addresses
+      if config[:from_address].nil? ||
+         config[:from_address].empty? ||
+         config[:recipient_addresses].nil? ||
+         config[:recipient_addresses].empty?
+
+        return nil
+      end
+
+      ensure_session_loaded(request)
+
+      # NOTE: be very careful pulling data out of request in the view...it is
+      # NOT cleaned, and may contain private data (e.g. passwords), so 
+      # scrutinize any use of @request in the views!
+
+      body_hash =
+        { :exception =>    exception,
+          :backtrace =>    backtrace,
+          :status_code =>  status_code,
+          :request_data => request_data,
+          :request =>      request 
+        }
+
+      body_hash.merge! extract_data_from_request_data(request_data)
+      from         config[:from_address]
+      recipients   config[:recipient_addresses]
+      subject      "[#{proc_name + (proc_name ? ' ' : '')}" +
+                   "#{config[:subject_prefix]}] " +
+                   "#{exception.class.name}: " +
+                   "#{exception.message.inspect}"
+      body         body_hash
+      sent_on      Time.now
+      content_type 'text/plain'
+    end
+
+    # helper to force loading of session data in case of lazy loading (Rails
+    # 2.3). if the argument isn't a request object, then don't bother, cause
+    # it won't have session.
+    #---------------------------------------------------------------------------
+    def ensure_session_loaded(request)
+      request.session.inspect if !request.nil? && request.respond_to?(:session)
+      true
+    end
+
+    # extract relevant (and serializable) data from a request object
+    #---------------------------------------------------------------------------
+    def extract_data_from_request_data(request_data)
+      if request_data
+        { :host => host_from_request_data(request_data),
+          :protocol => protocol_from_request_data(request_data),
+          :uri => uri_from_request_data(request_data)
+        }
+      else
+        {}
+      end
+    end
+
+    # extract the host from request object
+    #---------------------------------------------------------------------------
+    def host_from_request_data(request_data)
+      request_data['HTTP_X_REAL_IP'] ||
+        request_data['HTTP_X_FORWARDED_HOST'] ||
+        request_data['HTTP_HOST']
+    end
+
+    # extract protocol from request object
+    #---------------------------------------------------------------------------
+    def protocol_from_request_data(request_data)
+      request_data['SERVER_PROTOCOL']
+    end
+
+    # extract URI from request object
+    #---------------------------------------------------------------------------
+    def uri_from_request_data(request_data)
+      request_data['REQUEST_URI']
+    end
+
+  end
+
+end

data/lib/wrangler/wrangler_exceptions.rb

@@ -0,0 +1,63 @@
+# a bunch of handy exceptions. using the Http ones will require rails
+module Wrangler
+
+  # base class for all the http-related exception classes
+  #-----------------------------------------------------------------------------
+  class HttpStatusError < Exception
+    def initialize(status_code, addl_msg = nil)
+      @status_code = status_code
+      @addl_msg = addl_msg
+
+      full_message = self.class.status_to_msg(status_code)
+      full_message += addl_msg unless addl_msg.nil?
+
+      super(full_message)
+    end
+
+    attr_reader :status_code, :addl_msg
+
+    # accepts either a Fixnum status code or a symbol representation of a
+    # status code (e.g. 404 or :not_found)
+    # yes, this is total duplication of code in
+    # action_controller/status_codes.rb, but it's been made a private instance
+    # method in the module.
+    #---------------------------------------------------------------------------
+    def self.status_to_msg(status)
+      case status
+      when Fixnum then
+        "#{status} #{ActionController::StatusCodes::STATUS_CODES[status]}".strip
+      when Symbol then
+        status_to_msg(ActionController::StatusCodes::SYMBOL_TO_STATUS_CODE[status] ||
+          "500 Unknown Status #{status.inspect}")
+      else
+        status.to_s
+      end
+    end
+  end
+
+
+  class HttpUnauthorized < HttpStatusError
+    def initialize(msg = nil); super(401, msg); end
+  end
+
+  class HttpNotFound < HttpStatusError
+    def initialize(msg = nil); super(404, msg); end
+  end
+
+  class HttpNotAcceptable < HttpStatusError
+    def initialize(msg = nil); super(406, msg); end
+  end
+
+  class HttpInternalServerError < HttpStatusError
+    def initialize(msg = nil); super(500, msg); end
+  end
+
+  class HttpNotImplemented < HttpStatusError
+    def initialize(msg = nil); super(501, msg); end
+  end
+  
+  class HttpServiceUnavailable < HttpStatusError
+    def initialize(msg = nil); super(503, msg); end
+  end
+
+end

data/lib/wrangler/wrangler_helper.rb

@@ -0,0 +1,95 @@
+module Wrangler
+  WRANGLER_ROOT = "#{File.dirname(__FILE__)}/../.."
+
+  # make all of these instance methods act as  module functions as well
+  # (any instance method below this gets added as a module function as well)
+  module_function
+
+  # utility to determine if a class has another class as its ancestor. 
+  #
+  # returns the ancestor class (if any) that is found to be the ancestor
+  # of klass (will return the nearest ancestor in other_klasses).
+  # returns nil or false otherwise.
+  #
+  # arguments:
+  #   - klass: the class we're determining whether it has one of the other
+  #            classes as an ancestor
+  #   - other_klasses: a Class, an Array (or any other container that responds
+  #                    to include?() ) of Classes
+  #-----------------------------------------------------------------------------
+  def class_has_ancestor?(klass, other_klasses)
+    return nil if !klass.is_a?(Class)
+
+    other_klasses = [other_klasses] if other_klasses.is_a?(Class)
+
+    current_klass = klass
+    while current_klass
+      return current_klass if other_klasses.include?(current_klass)
+      current_klass = current_klass.superclass
+    end
+
+    return false
+  end
+
+
+  # given an array of search directory strings (or a single directory string),
+  # searches for files matching pattern.
+  #
+  # pattern expressed in cmd line wildcards...like "*.rb" or "foo.?"...
+  # and may contain subdirectories.
+  #---------------------------------------------------------------------------
+  def find_file_matching_pattern(search_dirs, pattern)
+    search_dirs = [search_dirs] unless search_dirs.is_a?(Array)
+
+    search_dirs.each do |d|
+      matches = Dir.glob(File.join(d, pattern))
+      return matches.first if matches.size > 0
+    end
+    return nil
+  end
+
+  # log the exception using logger if available. if object does not have a
+  # logger, will just puts()
+  #-----------------------------------------------------------------------------
+  def log_exception(exception, request_data = nil, status_code = nil)
+    msgs = []
+
+    msgs << "An exception was caught (#{exception.class.name}):"
+    msgs << exception.message
+    unless request_data.blank?
+      msgs <<  "Request params were:"
+      msgs <<  request_data.inspect
+    end
+    unless status_code.blank?
+      msgs <<  "Handling with status code: #{status_code}"
+    end
+    unless exception.backtrace.blank?
+      msgs <<  exception.backtrace.join("\n  ")
+    end
+
+    log_error msgs
+  end
+
+  # handles logging error messages, using logger if available and puts otherwise
+  #-----------------------------------------------------------------------------
+  def log_error(msgs)
+    unless msgs.is_a?(Array)
+      msgs = [msgs]
+    end
+
+    msgs.each do |m|
+      if respond_to?(:logger)
+        logger.error m
+      else
+        puts m
+      end
+    end
+  end
+
+  # shorthand access to the exception handling config
+  #-----------------------------------------------------------------------------
+  def config
+    Wrangler::ExceptionHandler.config
+  end
+
+end

data/lib/wrangler.rb

@@ -0,0 +1,284 @@
+require 'wrangler/wrangler_helper.rb'
+require 'wrangler/exception_handler.rb'
+require 'wrangler/exception_notifier.rb'
+
+module Wrangler
+
+  def self.included(base)
+    # only add in the controller-specific methods if the including class is one
+    if class_has_ancestor?(base, ActionController::Base)
+      base.send(:include, ControllerMethods)
+
+      # conditionally including these methods (each wrapped in a separate
+      # module) based on the configuration of whether to handle exceptions in
+      # the given environment or not. this allows the default implementation
+      # of the two rescue methods to run when Wrangler-based exception handling
+      # is disabled.
+
+      if Wrangler::ExceptionHandler.config[:handle_public_errors]
+        Rails.logger.info "Configuring #{base.name} with Wrangler's rescue_action_in_public"
+        base.send(:include, PublicControllerMethods)
+      else
+        Rails.logger.info "NOT Configuring #{base.name} with Wrangler's rescue_action_in_public"
+      end
+
+      if Wrangler::ExceptionHandler.config[:handle_local_errors]
+        Rails.logger.info "Configuring #{base.name} with Wrangler's rescue_action_locally"
+        base.send(:include, LocalControllerMethods)
+      else
+        Rails.logger.info "NOT configuring #{base.name} with Wrangler's rescue_action_locally"
+      end
+    end
+  end
+
+
+  # methods to only be included into a controller if Wrangler is configured to
+  # handle exceptions for public reqeusts. (Conditionally included into
+  # controllers in the Wrangler::included() method).
+  #-----------------------------------------------------------------------------
+  module PublicControllerMethods
+    # override default behavior and let Wrangler handle the exception for
+    # public (non-local) requests.
+    #---------------------------------------------------------------------------
+    def rescue_action_in_public(exception)
+      handle_exception(exception, :request => request,
+                       :render_errors => true)
+    end
+  end
+
+
+  # methods to only be included into a controller if Wrangler is configured to
+  # handle exceptions for local reqeusts. (Conditionally included into
+  # controllers in the Wrangler::included() method).
+  #-----------------------------------------------------------------------------
+  module LocalControllerMethods
+    # override default behavior and let Wrangler handle the exception for
+    # local requests.
+    #---------------------------------------------------------------------------
+    def rescue_action_locally(exception)
+      handle_exception(exception, :request => request,
+                       :render_errors => true)
+    end
+  end
+
+
+  # module of instance methods to be added to the class including Wrangler
+  # only if the including class is a rails controller class
+  #-----------------------------------------------------------------------------
+  module ControllerMethods
+
+    # called by rails if the exception has already been handled (e.g. by
+    # calling the rescue_from method in a controller and rendering a response)
+    #---------------------------------------------------------------------------
+    def rescue_with_handler(exception)
+      to_return = super
+      if to_return &&
+           (
+             (local_request? && Wrangler::ExceptionHandler.config[:handle_local_errors]) ||
+             (!local_request? && Wrangler::ExceptionHandler.config[:handle_public_errors])
+           )
+
+        handle_exception(exception, :request => request,
+                                    :render_errors => false)
+      end
+      to_return
+    end
+
+
+    # extract a hash of relevant (and serializable) parameters from a request
+    #---------------------------------------------------------------------------
+    def request_data_from_request(request)
+      return nil if request.nil?
+
+      request_data = {}
+      request.env.each_pair do |k,v|
+        next if skip_request_env?(k)
+
+        if self.respond_to?(:filter_parameters)
+          request_data.merge! self.send(:filter_parameters, k => v)
+        else
+          request_data.merge! k => v
+        end
+      end
+
+      params = {}
+      if self.respond_to?(:filter_parameters)
+        params.merge!(
+                      filter_parameters(request.env['action_controller.request.query_parameters'])
+                      )
+        params.merge!(
+                      filter_parameters(request.env['action_controller.request.request_parameters'])
+                      )
+      else
+        params.merge! request.env['action_controller.request.query_parameters']
+        params.merge! request.env['action_controller.request.request_parameters']
+      end
+
+      request_data.merge! :params => params unless params.blank?
+
+      return request_data
+    end
+
+
+    # determine if the request env param should be ommitted from the request
+    # data object, as specified in config (either for aesthetic reasons or
+    # because the param won't serialize well).
+    #---------------------------------------------------------------------------
+    def skip_request_env?(request_param)
+      skip_env = false
+      Wrangler::ExceptionHandler.config[:request_env_to_skip].each do |pattern|
+        if (pattern.is_a?(String) && pattern == request_param) ||
+           (pattern.is_a?(Regexp) && pattern =~ request_param)
+          skip_env = true
+          break
+        end
+      end
+
+      return skip_env
+    end
+
+
+    # select the proper file to render and do so. if the usual places don't
+    # turn up an appropriate template (see README), then fall back on
+    # an app-specific default error page or the ultimate back up gem default
+    # page.
+    #---------------------------------------------------------------------------
+    def render_error_template(exception, status_code)
+      file_path = get_view_path_for_exception(exception, status_code)
+      
+      # if that didn't work, fall back on configured app-specific default
+      if file_path.blank? || !File.exists?(file_path)
+        file_path = config[:default_error_template]
+
+        log_error(["Could not find an error template in the usual places " +
+                  "for exception #{exception.class}, status code " +
+                  "#{status_code}.",
+                  "Trying to default to app-specific default: '#{file_path}'"])
+      end
+
+      # as a last resort, just render the gem's 500 error
+      if file_path.blank? || !File.exists?(file_path)
+        file_path = config[:absolute_last_resort_default_error_template]
+
+        log_error("Still no template found. Using gem default of " +
+                  file_path)
+      end
+
+      log_error("Will render error template: '#{file_path}'")
+
+      render :file => file_path,
+             :status => status_code
+    end
+
+
+    # select the appropriate view path for the exception/status code. see
+    # README or the code for the different attempts that are made to find
+    # a template.
+    #---------------------------------------------------------------------------
+    def get_view_path_for_exception(exception, status_code)
+
+      # maintenance note: this method has lots of RETURN statements, so be
+      # a little careful, but basically, it returns as soon as it finds a
+      # file match, so there shouldn't be any processing to perform after
+      # a match is found. any such logic does not belong in this method
+
+      if exception.is_a?(Class)
+        exception_class = exception
+      else
+        exception_class = exception.class
+      end
+
+      # Note: this converts "::" to "/", so views need to be nested under
+      # exceptions' modules if appropriate
+      exception_filename_root = exception_class.name.underscore
+
+      template_mappings = nil
+      case request.format
+      when /html/
+        response_format = 'html'
+        template_mappings = config[:error_class_html_templates]
+      when /js/
+        response_format = 'js'
+        template_mappings = config[:error_class_js_templates]
+      when /xml/
+        'xml'
+      end
+      format_extension_pattern = ".#{response_format || ''}*"
+
+      if template_mappings
+
+        # search for direct mapping from exception name to error template
+
+        if template_mappings[exception_class]
+          error_file = template_mappings[exception_class]
+
+          return error_file if File.exists?(error_file)
+
+          log_error("Found mapping from exception class " +
+                    "#{exception_class.name} to error file '#{error_file}', " +
+                    "but error file was not found")
+        end
+
+        # search for mapping from an ancestor class to error template
+
+        ancestor_class =
+          Wrangler::class_has_ancestor?(exception_class.superclass,
+                                       template_mappings)
+
+        if ancestor_class
+          error_file = template_mappings[ancestor_class]
+
+          return error_file if File.exists?(error_file)
+
+          log_error("Found mapping from ancestor exception class " +
+                    "#{ancestor_class.name} to error file '#{error_file}', " +
+                    "but error file was not found")
+        end
+
+      end # end if template_mappings
+
+      # search for a file named after the exception in one of the search dirs
+
+      search_paths = [ config[:error_template_dir],
+                       File.join(RAILS_ROOT, 'public'),
+                       File.join(WRANGLER_ROOT, 'rails', 'app', 'views', 'wrangler')
+                     ]
+
+      # find files in specified directory like 'exception_class_name.format', e.g.
+      # standard_error.html or standard_error.js.erb
+      exception_pattern = "#{exception_filename_root}#{format_extension_pattern}"
+      file_path = find_file_matching_pattern(search_paths, exception_pattern)
+
+      return file_path if file_path
+
+      # search for a file named after the error status code in search dirs
+
+      status_code_pattern = "#{status_code}#{format_extension_pattern}"
+      file_path = find_file_matching_pattern(search_paths, status_code_pattern)
+
+      return file_path if file_path
+
+      # search for a file named after ancestors of the exception in search dirs
+
+      # look through exception's entire ancenstry to see if there's a matching
+      # template in the search directories
+      curr_ancestor = exception_class.superclass
+      while curr_ancestor
+        # find files in specified directory like 'exception_class_name.format', e.g.
+        # standard_error.html or standard_error.js.erb
+        exception_pattern =
+          "#{curr_ancestor.name.underscore}#{format_extension_pattern}"
+        file_path = find_file_matching_pattern(search_paths, exception_pattern)
+
+        return file_path if file_path
+
+        curr_ancestor = curr_ancestor.superclass
+      end
+
+      # didn't find anything
+      return nil
+    end
+
+  end # end ControllerMethods module
+
+end # end Wrangler module

data/rails/app/views/wrangler/400.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Unable to Process Requested Data</h1>
+
+  <p>Reloading the page will probably not help.</p>
+</div>

data/rails/app/views/wrangler/401.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Not Authorized</h1>
+
+  <p>You are not authorized to access this resource. You may be either not logged in at all, or not logged in as the appropriate user.</p>
+</div>

data/rails/app/views/wrangler/403.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Access Restricted</h1>
+
+  <p>If you need access to this resource please contact support or an administrator.</p>
+</div>

data/rails/app/views/wrangler/404.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>The page you were looking for doesn't exist.</h1>
+
+  <p>You may have mistyped the address or the page may have moved.</p>
+</div>

data/rails/app/views/wrangler/405.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Invalid Method.</h1>
+
+  <p>This resource only accepts certain HTTP methods.</p>
+</div>

data/rails/app/views/wrangler/410.html

@@ -0,0 +1,7 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Requested resource is no longer available</h1>
+
+  <p>Please remove bookmarks to this resource.</p>
+	<p>If you arrived here via a link from somewhere else please inform them of the broken link.</p>
+</div>

data/rails/app/views/wrangler/422.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Unprocessable Request</h1>
+
+  <p>The request was well-formed but was unable to be followed due to semantic errors.</p>
+</div>

data/rails/app/views/wrangler/423.html

@@ -0,0 +1,7 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>The change you wanted was rejected because the resource is locked</h1>
+
+  <p>It might become available again soon, if you try again!</p>
+  <p>Maybe you tried to change something you didn't have access to.</p>
+</div>

data/rails/app/views/wrangler/500.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+    <h1>We're sorry, but something went wrong.</h1>
+
+    <p>We've been notified about this issue and we'll take a look at it shortly.</p>
+</div>

data/rails/app/views/wrangler/501.html

@@ -0,0 +1,8 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+  <h1>Not Implemented</h1>
+
+  <p>Please remove bookmarks to this resource.</p>
+	<p>You have tried to access a feature that has not been implemented.</p> 
+	<p>If you arrived here via a link from somewhere else please inform them of the broken link.</p>
+</div>

data/rails/app/views/wrangler/503.html

@@ -0,0 +1,6 @@
+<!-- This file lives in gems/wrangler/rails/app/views/wrangler. See README for instructions on customizing. -->
+<div class="dialog">
+    <h1>The server is temporarily unavailable.</h1>
+  
+    <p>The resource you requested is temporarilly unavailable due to server overload, maintenance, or other downtime. Generally, this is a temporary state.</p>
+</div>