Merge branch 'master' of https://github.com/dblock/grape

Author: Michael Bleigh

README.markdown

@@ -62,6 +62,29 @@ And would respond to the following routes:
 
 Serialization takes place automatically. For more detailed usage information, please visit the [Grape Wiki](http://github.com/intridea/grape/wiki).
 
+## Raising Errors
+
+You can raise errors explicitly.
+
+    error!("Access Denied", 401)
+
+You can also return JSON formatted objects explicitly by raising error! and passing a hash instead of a message.
+
+    error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
+
+## Exception Handling
+
+By default Grape does not catch all unexpected exceptions. This means that the web server will handle the error and render the default error page as a result. It is possible to trap all exceptions by setting `rescue_all_errors true` instead. You may change the error format to JSON by using `error_format :json` and set the default error status to 200 with `default_error_status 200`. You may also include the complete backtrace of the exception with `rescue_with_backtrace true` either as text (for the :txt format) or as a :backtrace field in the json (for the :json format).
+
+    class Twitter::API < Grape::API
+      rescue_all_errors true
+      rescue_with_backtrace true
+      error_format :json
+      default_error_status 200
+
+      # api methods
+    end
+
 ## Note on Patches/Pull Requests
 
 * Fork the project.

lib/grape/api.rb

@@ -50,7 +50,7 @@ def set(key, value)
       def prefix(prefix = nil)
         prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
       end
-      
+
       # Specify an API version.
       #
       # @example API with legacy support.
@@ -79,6 +79,27 @@ def default_format(new_format = nil)
         new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
       end
 
+      # Specify the format for error messages.
+      # May be `:json` or `:txt` (default).
+      def error_format(new_format = nil)
+        new_format ? set(:error_format, new_format.to_sym) : settings[:error_format]
+      end
+
+      # Specify the default status code for errors.
+      def default_error_status(new_status = nil)
+        new_status ? set(:default_error_status, new_status) : settings[:default_error_status]
+      end
+
+      # Specify whether to rescue all errors.
+      def rescue_all_errors(new_value = true)
+        set(:rescue_all_errors, new_value)
+      end
+
+      # Specify whether to include error backtrace with errors.
+      def rescue_with_backtrace(new_value = true)
+        set(:rescue_with_backtrace, new_value)
+      end
+
       # Add helper methods that will be accessible from any
       # endpoint within this namespace (and child namespaces).
       #
@@ -217,7 +238,7 @@ def nest(*blocks, &block)
 
       def build_endpoint(&block)
         b = Rack::Builder.new
-        b.use Grape::Middleware::Error
+        b.use Grape::Middleware::Error, :default_status => settings[:default_error_status] || 403, :rescue => settings[:rescue_all_errors], :format => settings[:error_format] || :txt, :backtrace => settings[:rescue_with_backtrace]
         b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
         b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
         b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version

lib/grape/middleware/error.rb

@@ -3,19 +3,84 @@
 module Grape
   module Middleware
     class Error < Base
+    
+      def default_options
+      { 
+        :default_status => 403, # default status returned on error
+        :rescue => true, # true to rescue all exceptions
+        :default_message => "",
+        :format => :txt,
+        :formatters => {},
+        :backtrace => false, # true to display backtrace
+      }
+      end
+
+      FORMATTERS = {
+        :json => :format_json,
+        :txt => :format_txt,
+      }
+
+      def formatters
+        FORMATTERS.merge(options[:formatters])
+      end
+
+      def formatter_for(api_format)
+        spec = formatters[api_format]
+        case spec
+        when nil
+          lambda { |obj| obj }
+        when Symbol
+          method(spec)
+        else
+          spec
+        end
+      end
+
+      def format_json(message, backtrace)
+        result = message.is_a?(Hash) ? message : { :error => message }
+        if (options[:backtrace] && backtrace && ! backtrace.empty?)
+          result = result.merge({ :backtrace => backtrace })
+        end
+        result.to_json
+      end
+      
+      def format_txt(message, backtrace)
+        result = message.is_a?(Hash) ? message.to_json : message
+        if options[:backtrace] && backtrace && ! backtrace.empty?
+          result += "\r\n "
+          result += backtrace.join("\r\n ")
+        end
+        result
+      end
+
       def call!(env)
         @env = env
-        result = catch :error do
-          @app.call(@env)
+        
+        begin
+          error_response(catch(:error){ 
+            return @app.call(@env) 
+          })
+        rescue Exception => e
+          raise unless options[:rescue]
+          error_response({ :message => e.message, :backtrace => e.backtrace })
         end
 
-        result ||= {}
-        result.is_a?(Hash) ? error_response(result) : result
       end
 
       def error_response(error = {})
-        Rack::Response.new([(error[:message] || options[:default_message])], error[:status] || 403, error[:headers] || {}).finish
+        status = error[:status] || options[:default_status]
+        message = error[:message] || options[:default_message]
+        headers = error[:headers] || {}
+        backtrace = error[:backtrace] || []
+        Rack::Response.new([format_message(message, backtrace, status)], status, headers).finish
+      end
+      
+      def format_message(message, backtrace, status)
+        formatter = formatter_for(options[:format])
+        throw :error, :status => 406, :message => "The requested format #{options[:format]} is not supported." unless formatter        
+        formatter.call(message, backtrace)
       end
+      
     end
   end
 end

spec/grape/api_spec.rb

@@ -20,7 +20,7 @@ def app; subject end
       last_response.status.should eql 404
     end
   end
-  
+
   describe '.version' do
     it 'should set the API version' do
       subject.version 'v1'
@@ -471,4 +471,101 @@ def two
       last_response.status.should eql 200
     end
   end
+  
+  describe ".rescue_all_errors" do
+    it 'should not rescue all errors when rescue_all_errors is false' do
+      subject.rescue_all_errors false
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      lambda { get '/exception' }.should raise_error
+    end
+    it 'should rescue all errors' do
+      subject.rescue_all_errors true
+      subject.get '/exception' do
+        raise "rain!"
+      end
+      get '/exception'
+      last_response.status.should eql 403
+    end
+  end
+  
+  describe ".error_format" do
+    it 'should rescue all errors and return :txt' do
+      subject.rescue_all_errors true
+      subject.error_format :txt
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      last_response.body.should eql "rain!"
+    end
+    it 'should rescue all errros and return :txt with backtrace' do
+      subject.rescue_all_errors true
+      subject.error_format :txt
+      subject.rescue_with_backtrace true
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      last_response.body.start_with?("rain!\r\n").should be_true
+    end
+    it 'should rescue all errors and return :json' do
+      subject.rescue_all_errors true
+      subject.error_format :json
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      last_response.body.should eql '{"error":"rain!"}'
+    end
+    it 'should rescue all errors and return :json with backtrace' do
+      subject.rescue_all_errors true
+      subject.error_format :json
+      subject.rescue_with_backtrace true
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      json = JSON.parse(last_response.body)
+      json["error"].should eql 'rain!'
+      json["backtrace"].length.should > 0
+    end
+    it 'should rescue error! and return txt' do
+      subject.error_format :txt
+      subject.get '/error' do
+        error!("Access Denied", 401)
+      end    
+      get '/error'
+      last_response.body.should eql "Access Denied"
+    end
+    it 'should rescue error! and return json' do
+      subject.error_format :json
+      subject.get '/error' do
+        error!("Access Denied", 401)
+      end    
+      get '/error'
+      last_response.body.should eql '{"error":"Access Denied"}'
+    end
+  end
+  
+  describe ".default_error_status" do
+    it 'should allow setting default_error_status' do
+      subject.rescue_all_errors true
+      subject.default_error_status 200
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      last_response.status.should eql 200
+    end
+    it 'should have a default error status' do
+      subject.rescue_all_errors true
+      subject.get '/exception' do
+        raise "rain!"
+      end    
+      get '/exception'
+      last_response.status.should eql 403
+    end
+  end
 end

spec/grape/endpoint_spec.rb

@@ -73,8 +73,6 @@ def app; subject end
     end
 
     it 'should accept an object and render it in format' do
-      pending
-
       subject.get '/hey' do
         error!({'dude' => 'rad'}, 403)
       end

spec/grape/middleware/error_spec.rb

@@ -46,4 +46,4 @@ def app
   context 'with formatting' do
 
   end
-end
+end