restful_json 3.3.4 → 3.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MGQzMzcyMzc1ZDdjMTQ2NTk2NzBhZGUwMDQzOTM3ZTIyMWU0MGEzNA==
+    ZjgzMjdmNjljNDk3NmVjMGY1MGY4ZWIxMTdhNzQ5OTM1MTA5YTJkYQ==
   data.tar.gz: !binary |-
-    MDNkZmFjZDdkOGQ4YzkxMWJkNzc1NjBlZmYwYjcwODhkODBkNjMxNw==
+    ODgwNzg5ODUwMTQwNjBhOTIyZjNlNDNlY2U0ZWY1ZDYxNjE5NmU5Mw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    MTgyMjc3OGMzYzZiZjE4Y2FkMjJlYjk4Mzc1ZmU0YjIzMDdiYjBmZWYzZmYw
-    MDFlMGQzZWU0Y2VhNjdkNzNiYTBhNzZhYWY3YzE1OTZiNTgzMmZkYmQyMDk1
-    NzQ1ZmY1ZmVkOTI0MTRjZWZiODRiNzJhYzU1MzI5YWFkN2FkOTE=
+    OGYwZjQ5ZjljOWJmZTUzN2RlYTM0OGNmNGI5ZDViNDIzNDMxOTFlNjQ5YmMx
+    NzY5MTdhMzk0YmQ0MGNmZmJkMjQwMDMwNGYzYjllNDg0OWM3Y2ZmZjkyMDI2
+    NjVlN2ZhMTRhMTljZGE3NWI3YzNjYWYxMjBhODhlNTk3MTYwZmQ=
   data.tar.gz: !binary |-
-    OWNhMDhhODdhZjU4ZTA0MDMzNjRlOGM3NGEzYTlkNmQzNmFiMGZjMzYxZDM0
-    NjY3ZjNmOGM3YjgzMDQ5N2Y2ZjQ5YjE0ZWZjYWNhYzlhMWNlODk4ZGNkYWE3
-    NTAxNTI4YTAzOTAyOWNmNGE1NGI1ZGVjYzYzMDA1NTVjZjI3ZmI=
+    YTVjM2YyNjNhYjAyMDdiMzM3M2JlNGExMWYwODRjYWExZGM5NWQxZDU1MmM5
+    NzAyYTU3MjY3MWFiYzM1NjYzYTUyNTlmNWRjNjEzODljYzNkZmU4NzRkYTI1
+    MDE1MTFkNGYxMDNiZDc1ZWU5ZTc0YjYzZDk2MzczNDVlMmU2MDE=

data/README.md

@@ -701,6 +701,74 @@ You would get the response:
 
 For more realistic use that takes advantage of existing configuration in the controller, take a look at the controller in `lib/restful_json/controller.rb` to see how the actions are defined, and just copy/paste into your controller or module, etc.
 
+### Error Handling
+
+#### Properly Handling Non-controller-action Errors
+
+Some things restful_json can't do in the controller, like responding with json for a json request when the route is not setup correctly or an action is missing.
+
+Rails 4 has basic error handling defined in the [public_exceptions][public_exceptions] and [show_exceptions][show_exceptions] Rack middleware.
+
+Rails 3.2.x has support for `config.exceptions_app` which can be defined as the following to simulate Rails 4 exception handling:
+
+    config.exceptions_app = lambda do |env|
+      exception = env["action_dispatch.exception"]
+      status = env["PATH_INFO"][1..-1]
+      request = ActionDispatch::Request.new(env)
+      content_type = request.formats.first
+      body = { :status => status, :error => exception.message }
+      format = content_type && "to_#{content_type.to_sym}"
+      if format && body.respond_to?(format)
+        formatted_body = body.public_send(format)
+        [status, {'Content-Type' => "#{content_type}; charset=#{ActionDispatch::Response.default_charset}",
+                'Content-Length' => body.bytesize.to_s}, [formatted_body]]
+      else
+        found = false
+        path = "#{public_path}/#{status}.#{I18n.locale}.html" if I18n.locale
+        path = "#{public_path}/#{status}.html" unless path && (found = File.exist?(path))
+
+        if found || File.exist?(path)
+          [status, {'Content-Type' => "text/html; charset=#{ActionDispatch::Response.default_charset}",
+                  'Content-Length' => body.bytesize.to_s}, [File.read(path)]]
+        else
+          [404, { "X-Cascade" => "pass" }, []]
+        end
+      end
+    end
+
+That is just a collapsed version of the behavior of [public_exceptions][public_exceptions] as of April 2013, pre-Rails 4.0.0, so please look at the latest version and adjust accordingly. Use at your own risk, obviously.
+
+Unfortunately, this doesn't work for Rails 3.1.x. However, in many scenarios there is the chance at a rare situation when the proper format is not returned to the client, even if everything is controlled as much as possible on the server. So, the client really needs to be able to handle such a case of unexpected format with a generic error.
+
+But, if you can make Rack respond a little better for some errors, that's great.
+
+#### Controller Error Handling Configuration
+
+The default configuration will rescue StandardError in each action method and will render as 404 for ActiveRecord::RecordNotFound or 500 for all other StandardError (and ancestors, like a normal rescue).
+
+There are a few options to customize the rescue and error rendering behavior.
+
+The `rescue_class` config option specifies what to rescue. Set to StandardError to behave like a normal rescue. Set to nil to just reraise everything rescued (to disable handling).
+
+The `rescue_handlers` config option is like a minimalist set of rescue blocks that apply to every action method. For example, the following would effectively `rescue => e` (rescuing `StandardError`) and then for `ActiveRecord::RecordNotFound`, it would uses response status `:not_found` (HTTP 404). Otherwise it uses status `:internal_server_error` (HTTP 500). In both cases the error message is `e.message`:
+
+    self.rescue_class = StandardError
+    self.rescue_handlers = [
+      {exception_classes: [ActiveRecord::RecordNotFound], status: :not_found},
+      {status: :internal_server_error}
+    ]
+
+In a slightly more complicated case, this configuration would catch all exceptions raised with each actinon method that had `ActiveRecord::RecordNotFound` as an ancestor and use the error message defined by i18n key 'api.not_found'. All other exceptions would use status `:internal_server_error` (because it is a default, and doesn't have to be specified) but would use the error message defined by i18n key 'api.internal_server_error':
+
+    self.rescue_class = Exception
+    self.rescue_handlers = [
+      {exception_ancestor_classes: [ActiveRecord::RecordNotFound], status: :not_found, i18n_key: 'api.not_found'.freeze},
+      {i18n_key: 'api.internal_server_error'.freeze}
+    ]
+
+
+The `return_error_data` config option will not only return a response with `status` and `error` but also an `error_data` containing the `e.class.name`, `e.message`, and cleaned `e.backtrace`.
+
 ### Release Notes
 
 #### restful_json v3.3
@@ -758,4 +826,6 @@ Copyright (c) 2013 Gary S. Weaver, released under the [MIT license][lic].
 [ar]: http://api.rubyonrails.org/classes/ActiveRecord/Relation.html
 [rails-api]: https://github.com/rails-api/rails-api
 [railscast320]: http://railscasts.com/episodes/320-jbuilder
+[public_exceptions]: https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/middleware/public_exceptions.rb
+[show_exceptions]: https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/middleware/show_exceptions.rb
 [lic]: http://github.com/rubyservices/restful_json/blob/master/LICENSE

data/lib/restful_json/config.rb

@@ -9,7 +9,10 @@ module RestfulJson
     :return_resource,
     :render_enabled,
     :use_permitters,
-    :avoid_respond_with
+    :avoid_respond_with,
+    :return_error_data,
+    :rescue_class,
+    :rescue_handlers
   ]
   
   class << self
@@ -22,12 +25,22 @@ end
 RestfulJson.configure do
   self.can_filter_by_default_using = [:eq]
   self.debug = false
-  self.filter_split = ','
+  self.filter_split = ','.freeze
   self.formats = :json, :html
   self.number_of_records_in_a_page = 15
-  self.predicate_prefix = '!'
+  self.predicate_prefix = '!'.freeze
   self.return_resource = false
   self.render_enabled = true
   self.use_permitters = true
   self.avoid_respond_with = true
+  self.return_error_data = true
+  # Set to nil to reraise StandardError in rescue vs. calling render_error(e) to render using restful_json
+  self.rescue_class = StandardError
+  # Ordered array of handlers to handle rescue of self.rescue_class or sub types. Can use optional i18n_key for message, but will default to e.message if not found.
+  # Eventually may support [DataMapper::ObjectNotFoundError], [MongoMapper::DocumentNotFound], etc.
+  # If no exception_classes or exception_ancestor_classes provided, it will always match self.rescue_class.
+  self.rescue_handlers = [
+    {exception_classes: [ActiveRecord::RecordNotFound], status: :not_found, i18n_key: 'api.not_found'.freeze},
+    {status: :internal_server_error, i18n_key: 'api.internal_server_error'.freeze}
+  ]
 end

data/lib/restful_json/controller.rb

@@ -197,6 +197,80 @@ module RestfulJson
       value && NILS.include?(value) ? nil : value
     end
 
+    def safe_i18n_t(i18n_key)
+      I18n.t(i18n_key)
+    rescue => e
+      logger.debug "failed to get i18n message for #{i18n_key.inspect}: #{e.message}\n#{e.backtrace.join('\n')}" if self.debug
+    end
+
+    # Returns self.return_error_data by default. To only return error_data in dev and test, use this:
+    # `def enable_long_error?; Rails.env.development? || Rails.env.test?; end`
+    def include_error_data?
+      self.return_error_data
+    end
+
+    # Searches through self.rescue_handlers for appropriate handler.
+    # self.rescue_handlers is an array of hashes where there is key :exception_classes and/or :exception_ancestor_classes
+    # along with :i18n_key and :status keys.
+    # :exception_classes contains an array of classes to exactly match the exception.
+    # :exception_ancestor_classes contains an array of classes that can match an ancestor of the exception.
+    # If exception handled, returns hash, hopefully containing keys :i18n_key and :status.
+    # Otherwise, returns nil which indicates that this exception should not be handled.
+    def exception_handling_data(e)
+      self.rescue_handlers.each do |handler|
+        return handler if (handler.key?(:exception_classes) && handler[:exception_classes].include?(e.class))
+        if handler.key?(:exception_ancestor_classes)
+          handler[:exception_ancestor_classes].each do |ancestor|
+            return handler if e.class.ancestors.include?(ancestor)
+          end
+        elsif !handler.key?(:exception_classes) && !handler.key?(:exception_ancestor_classes)
+          return handler
+        end
+      end
+      nil
+    end
+
+    def handle_or_raise(e)
+      raise e if self.rescue_class.nil?
+      handling_data = exception_handling_data(e)
+      raise e unless handling_data
+      # this is something we intended to rescue, so log it
+      logger.error(e)
+      # render error only if we haven't rendered response yet
+      render_error(e, handling_data) unless @performed_render
+    end
+
+    # Renders error using handling data options (where options are probably hash from self.rescue_handlers that was matched).
+    #
+    # If include_error_data? is true, it returns something like the following (with the appropriate HTTP status code via setting appropriate status in respond_do:
+    # {"status": "not_found",
+    #  "error": "Internationalized error message or e.message",
+    #  "error_data": {"type": "ActiveRecord::RecordNotFound", "message": "Couldn't find Bar with id=23423423", "trace": ["backtrace line 1", ...]}
+    # }
+    #
+    # If include_error_data? is false, it returns something like:
+    # {"status": "not_found", "error", "Couldn't find Bar with id=23423423"}
+    #
+    # It handles any format in theory that is supported by respond_to and has a `to_(some format)` method.
+    def render_error(e, handling_data)
+      i18n_key = handling_data[:i18n_key]
+      msg = i18n_key ? safe_i18n_t(i18n_key) : e.message
+      status = handling_data[:status] || :internal_server_error
+      if include_error_data?
+        respond_to do |format|
+          format.html { render notice: msg }
+          format.any { render request.format.to_sym => {:status => status, error: msg, error_data: {type: e.class.name, message: e.message, trace: Rails.backtrace_cleaner.clean(e.backtrace)}}, status: status }
+        end
+      else
+        respond_to do |format|
+          format.html { render notice: msg }
+          format.any { render request.format.to_sym => {:status => status, error: msg}, status: status }
+        end
+      end
+      # return exception so we know it was handled
+      e
+    end
+
     def render_or_respond(read_only_action, success_code = :ok)
       if self.render_enabled
         # 404/not found is just for update (not destroy, because idempotent destroy = no 404)
@@ -341,6 +415,8 @@ module RestfulJson
       @value = value
       instance_variable_set(@model_at_plural_name_sym, @value)
       render_or_respond(true)
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's show (get) method to return a resource.
@@ -350,6 +426,8 @@ module RestfulJson
       @value = @model_class.where(id: params[:id].to_s).first # don't raise exception if not found
       instance_variable_set(@model_at_singular_name_sym, @value)
       render_or_respond(true, @value.nil? ? :not_found : :ok)
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's new method (e.g. used for new record in html format).
@@ -358,6 +436,8 @@ module RestfulJson
       @value = @model_class.new
       instance_variable_set(@model_at_singular_name_sym, @value)
       render_or_respond(true)
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's edit method (e.g. used for edit record in html format).
@@ -367,6 +447,8 @@ module RestfulJson
       @value = @model_class.where(id: params[:id].to_s).first! # raise exception if not found
       instance_variable_set(@model_at_singular_name_sym, @value)
       @value
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's create (post) method to create a resource.
@@ -386,6 +468,8 @@ module RestfulJson
       @value.save
       instance_variable_set(@model_at_singular_name_sym, @value)
       render_or_respond(false, :created)
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's update (put) method to update a resource.
@@ -406,6 +490,8 @@ module RestfulJson
       @value.update_attributes(allowed_params) unless @value.nil?
       instance_variable_set(@model_at_singular_name_sym, @value)
       render_or_respond(true, @value.nil? ? :not_found : :ok)
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
 
     # The controller's destroy (delete) method to destroy a resource.
@@ -423,6 +509,8 @@ module RestfulJson
       else
         render_or_respond(false)
       end
+    rescue self.rescue_class => e
+      handle_or_raise(e)
     end
   end
 end

data/lib/restful_json/default_controller.rb

@@ -7,6 +7,12 @@ module RestfulJson
       include ::ActionController::StrongParameters
       include ::TwinTurbo::Controller
       include ::RestfulJson::Controller
+      
+      rescue_from Exception, :with => :render_error
+      rescue_from ActiveRecord::RecordNotFound, :with => :render_not_found
+      rescue_from ActionController::RoutingError, :with => :render_not_found
+      rescue_from ActionController::UnknownController, :with => :render_not_found
+      rescue_from AbstractController::ActionNotFound, :with => :render_not_found
     end
   end
 end

data/lib/restful_json/version.rb

@@ -1,3 +1,3 @@
 module RestfulJson
-  VERSION = '3.3.4'
+  VERSION = '3.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restful_json
 version: !ruby/object:Gem::Version
-  version: 3.3.4
+  version: 3.4.0
 platform: ruby
 authors:
 - Gary S. Weaver
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-12 00:00:00.000000000 Z
+date: 2013-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler