error messages can now be presented

CHANGELOG.md

@@ -10,6 +10,7 @@
 * [#703](https://github.com/intridea/grape/pull/703): Removed `Grape::Middleware::Auth::OAuth2` - [@dspaeth-faber](https://github.com/dspaeth-faber).
 * [#719](https://github.com/intridea/grape/pull/719): Allow passing options hash to a custom validator - [@elado](https://github.com/elado).
 * [#716](https://github.com/intridea/grape/pull/716): Calling `content-type` will now return the current content-type - [@dblock](https://github.com/dblock).
+* [#705](https://github.com/intridea/grape/pull/705): Errors can now be presented - [@dspaeth-faber](https://github.com/dspaeth-faber).
 * Your contribution here.
 
 0.8.0 (7/10/2014)

README.md

@@ -944,6 +944,38 @@ instead of a message.
 error!({ error: "unexpected error", detail: "missing widget" }, 500)
 ```
 
+When you'r error message is representable, a Hash with an option `with` or your
+status is documented with an `Entity` it will be presented.
+
+Examples:
+
+```ruby
+
+
+desc 'my route' , http_code:  [[408, 'Unauthorized', API::Error]],
+
+error!(Error.new(...), 400)
+error!({ message: 'An Error', with: API::Error }, 401)
+error!({ message: 'An Error' }, 408)
+
+```
+
+Error messages can be enriched with the status code, when you use a Hash or your message respond to
+`code`
+
+```ruby
+
+class API < Grape::API
+  add_http_code_on_error true
+
+  get '/' do
+    error!({message: 'Error'}, 404) # => result as json "{"message":"Error", "code":404}"
+  end
+end
+
+
+```
+
 ### Default Error HTTP Status Code
 
 By default Grape returns a 500 status code from `error!`. You can change this with `default_error_status`.

grape.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'virtus', '>= 1.0.0'
   s.add_runtime_dependency 'builder'
 
-  s.add_development_dependency 'grape-entity', '>= 0.2.0'
+  s.add_development_dependency 'grape-entity', '>= 0.4.4'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'maruku'
   s.add_development_dependency 'yard'

lib/grape/dsl/inside_route.rb

@@ -173,22 +173,7 @@ def present(*args)
                       else
                         [nil, args.first]
                       end
-        entity_class = options.delete(:with)
-
-        if entity_class.nil?
-          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
-          object_class = if object.respond_to?(:klass)
-                           object.klass
-                         else
-                           object.respond_to?(:first) ? object.first.class : object.class
-                         end
-
-          object_class.ancestors.each do |potential|
-            entity_class ||= (settings[:representations] || {})[potential]
-          end
-
-          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-        end
+        entity_class = entity_class_for_obj(object, options)
 
         root = options.delete(:root)
 
@@ -216,6 +201,27 @@ def present(*args)
       def route
         env["rack.routing_args"][:route_info]
       end
+
+      def entity_class_for_obj(object, options)
+        entity_class = options.delete(:with)
+
+        if entity_class.nil?
+          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
+          object_class = if object.respond_to?(:klass)
+                           object.klass
+                         else
+                           object.respond_to?(:first) ? object.first.class : object.class
+                         end
+
+          object_class.ancestors.each do |potential|
+            entity_class ||= (settings[:representations] || {})[potential]
+          end
+
+          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
+        end
+
+        entity_class
+      end
     end
   end
 end

lib/grape/dsl/request_response.rb

@@ -146,6 +146,16 @@ def represent(model_class, options)
           raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with] && options[:with].is_a?(Class)
           imbue(:representations, model_class => options[:with])
         end
+
+        # Specify if the http code should be added to
+        # the error message
+        def add_http_code_on_error(new_value = nil)
+          if new_value.nil?
+            settings[:add_http_code_on_error]
+          else
+            set(:add_http_code_on_error, new_value)
+          end
+        end
       end
     end
   end

lib/grape/endpoint.rb

@@ -238,7 +238,8 @@ def build_middleware
             rescue_options: settings[:rescue_options],
             rescue_handlers: merged_setting(:rescue_handlers),
             base_only_rescue_handlers: merged_setting(:base_only_rescue_handlers),
-            all_rescue_handler: settings[:all_rescue_handler]
+            all_rescue_handler: settings[:all_rescue_handler],
+            add_http_code_on_error: settings[:add_http_code_on_error]
 
       aggregate_setting(:middleware).each do |m|
         m = m.dup

lib/grape/error_formatter/base.rb

@@ -26,6 +26,36 @@ def formatter_for(api_format, options = {})
           end
         end
       end
+
+      module_function
+
+      def present(message, env)
+        present_options = {}
+        present_options[:with] = message.delete(:with) if message.is_a?(Hash)
+
+        presenter = env['api.endpoint'].entity_class_for_obj(message, present_options)
+
+        unless presenter
+          begin
+            http_codes = env['api.endpoint'].route.route_http_codes || []
+            found_code = http_codes.find do |http_code|
+              (http_code[0].to_i == env['api.endpoint'].status) && http_code[2].respond_to?(:represent)
+            end
+
+            presenter = found_code[2] if found_code
+          rescue
+            nil  # some bad specs don't define env
+          end
+        end
+
+        if presenter
+          embeds = { env: env }
+          embeds[:version] = env['api.version'] if env['api.version']
+          message = presenter.represent(message, embeds).serializable_hash
+        end
+
+        message
+      end
     end
   end
 end

lib/grape/error_formatter/json.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Json
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? message : { error: message }
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result = result.merge(backtrace: backtrace)

lib/grape/error_formatter/txt.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Txt
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? MultiJson.dump(message) : message
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result += "\r\n "

lib/grape/error_formatter/xml.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Xml
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? message : { message: message }
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result = result.merge(backtrace: backtrace)

lib/grape/middleware/error.rb

@@ -15,7 +15,8 @@ def default_options
           rescue_options: { backtrace: false }, # true to display backtrace
           rescue_handlers: {}, # rescue handler blocks
           base_only_rescue_handlers: {}, # rescue handler blocks rescuing only the base class
-          all_rescue_handler: nil # rescue handler block to rescue from all exceptions
+          all_rescue_handler: nil, # rescue handler block to rescue from all exceptions
+          add_http_code_on_error: false # add http code to error messages
         }
       end
 
@@ -76,6 +77,11 @@ def rack_response(message, status = options[:default_status], headers = { 'Conte
       end
 
       def format_message(message, backtrace)
+        if options[:add_http_code_on_error]
+          message.code = env['api.endpoint'].status if message.respond_to? :code
+          message =  message.merge(code: env['api.endpoint'].status) if message.respond_to? :merge
+        end
+
         format = env['api.format'] || options[:format]
         formatter = Grape::ErrorFormatter::Base.formatter_for(format, options)
         throw :error, status: 406, message: "The requested format '#{format}' is not supported." unless formatter

spec/grape/api_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'shared/versioning_examples'
+require 'grape-entity'
 
 describe Grape::API do
   subject { Class.new(Grape::API) }
@@ -1762,6 +1763,54 @@ def self.call(object, env)
     end
   end
 
+  describe '.add_http_code_on_error' do
+    it 'allows adding http status code' do
+      subject.add_http_code_on_error true
+
+      subject.desc 'some desc', http_codes: [[401, 'Unauthorized', Class.new(Grape::Entity)]]
+
+      subject.get '/exception' do
+        error!({}, 408)
+      end
+
+      get '/exception'
+      expect(last_response.status).to eql 408
+      expect(last_response.body).to eql({ code: 408 }.to_json)
+    end
+  end
+
+  describe 'http_codes' do
+
+    let(:error_presenter) do
+      Class.new(Grape::Entity) do
+        expose :code
+        expose :static
+
+        def static
+          'some static text'
+        end
+
+      end
+
+    end
+
+    it 'is used as presenter' do
+
+      subject.add_http_code_on_error true
+
+      subject.desc 'some desc', http_codes: [[401, 'Error'], [408, 'Unauthorized', error_presenter], [409, 'Error']]
+
+      subject.get '/exception' do
+        error!({}, 408)
+      end
+
+      get '/exception'
+      expect(last_response.status).to eql 408
+      expect(last_response.body).to eql({ code: 408, static: 'some static text' }.to_json)
+    end
+
+  end
+
   context 'routes' do
     describe 'empty api structure' do
       it 'returns an empty array of routes' do

spec/grape/dsl/request_response_spec.rb

@@ -118,6 +118,13 @@ def self.imbue(key, value)
           subject.represent :ThisClass, with: presenter
         end
       end
+
+      describe '.add_http_code_on_error' do
+        it 'sets a flag if the error code should be added to the error' do
+          expect(subject).to receive(:set).with(:add_http_code_on_error, true)
+          subject.add_http_code_on_error true
+        end
+      end
     end
   end
 end

spec/grape/middleware/error_spec.rb

@@ -1,6 +1,17 @@
 require 'spec_helper'
+require 'grape-entity'
 
 describe Grape::Middleware::Error do
+  module ErrorSpec
+    class ErrorEntity < Grape::Entity
+      expose :code
+      expose :static
+
+      def static
+        'static text'
+      end
+    end
+  end
   class ErrApp
     class << self
       attr_accessor :error
@@ -13,12 +24,16 @@ def call(env)
   end
 
   def app
+    opts = options
     Rack::Builder.app do
-      use Grape::Middleware::Error, default_message: 'Aww, hamburgers.'
+      use Spec::Support::EndpointFaker
+      use Grape::Middleware::Error, opts
       run ErrApp
     end
   end
 
+  let(:options) {  { default_message: 'Aww, hamburgers.' } }
+
   it 'sets the status code appropriately' do
     ErrApp.error = { status: 410 }
     get '/'
@@ -42,4 +57,21 @@ def app
     get '/'
     expect(last_response.body).to eq('Aww, hamburgers.')
   end
+
+  context 'with http code' do
+    let(:options) {  { default_message: 'Aww, hamburgers.', add_http_code_on_error: true } }
+    it 'adds the status code if wanted' do
+      ErrApp.error = { message: {} }
+      get '/'
+
+      expect(last_response.body).to eq({ code: 200 }.to_json)
+    end
+
+    it 'presents an error message' do
+      ErrApp.error = { message: { with: ErrorSpec::ErrorEntity } }
+      get '/'
+
+      expect(last_response.body).to eq({ code: 200, static: 'static text' }.to_json)
+    end
+  end
 end