grape 0.6.1 → 0.7.0

data/Rakefile

@@ -15,7 +15,12 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
 end
 
 task :spec
-task :default => :spec
+
+require 'rainbow/ext/string' unless String.respond_to?(:color)
+require 'rubocop/rake_task'
+Rubocop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]
 
 begin
   require 'yard'

data/UPGRADING.md

@@ -0,0 +1,124 @@
+Upgrading Grape
+===============
+
+### Upgrading to 0.7.0
+
+#### Changes in Exception Handling
+
+Assume you have the following exception classes defined.
+
+```ruby
+class ParentError < StandardError; end
+class ChildError < ParentError; end
+```
+
+In Grape <= 0.6.1, the `rescue_from` keyword only handled the exact exception being raised. The following code would rescue `ParentError`, but not `ChildError`.
+
+```ruby
+rescue_from ParentError do |e|
+  # only rescue ParentError
+end
+```
+
+This made it impossible to rescue an exception hieararchy, which is a more sensible default. In Grape 0.7.0 or newer, both `ParentError` and `ChildError` are rescued.
+
+```ruby
+rescue_from ParentError do |e|
+  # rescue both ParentError and ChildError
+end
+```
+
+To only rescue the base exception class, set `rescue_subclasses: false`.
+
+```ruby
+rescue_from ParentError, rescue_subclasses: false do |e|
+  # only rescue ParentError
+end
+```
+
+See [#544](https://github.com/intridea/grape/pull/544) for more information.
+
+
+#### Changes in the Default HTTP Status Code
+
+In Grape <= 0.6.1, the default status code returned from `error!` was 403.
+
+```ruby
+error! "You may not reticulate this spline!" # yields HTTP error 403
+```
+
+This was a bad default value, since 403 means "Forbidden". Change any call to `error!` that does not specify a status code to specify one. The new default value is a more sensible default of 500, which is "Internal Server Error".
+
+```ruby
+error! "You may not reticulate this spline!", 403 # yields HTTP error 403
+```
+
+You may also use `default_error_status` to change the global default.
+
+```ruby
+default_error_status 400
+```
+
+See [#525](https://github.com/intridea/Grape/pull/525) for more information.
+
+
+#### Changes in Parameter Declaration and Validation
+
+In Grape <= 0.6.1, `group`, `optional` and `requires` keywords with a block accepted either an `Array` or a `Hash`.
+
+```ruby
+params do
+  requires :id, type: Integer
+  group :name do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
+
+This caused the ambiguity and unexpected errors described in [#543](https://github.com/intridea/Grape/issues/543).
+
+In Grape 0.6.2, the `group`, `optional` and `requires` keywords take an additional `type` attribute which defaults to `Array`. This means that without a `type` attribute, these nested parameters will no longer accept a single hash, only an array (of hashes).
+
+Whereas in 0.6.1 the API above accepted the following json, it no longer does in 0.6.2.
+
+```json
+{
+  "id": 1,
+  "name": {
+    "first_name": "John",
+    "last_name" : "Doe"
+  }
+}
+```
+
+The `params` block should now read as follows.
+
+```ruby
+params do
+  requires :id, type: Integer
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
+
+See [#545](https://github.com/intridea/Grape/pull/545) for more information.
+
+
+### Upgrading to 0.6.0
+
+In Grape <= 0.5.0, only the first validation error was raised and processing aborted. Validation errors are now collected and a single `Grape::Exceptions::ValidationErrors` exception is raised. You can access the collection of validation errors as `.errors`.
+
+```ruby
+rescue_from Grape::Exceptions::Validations do |e|
+  Rack::Response.new({
+    status: 422,
+    message: e.message,
+    errors: e.errors
+  }.to_json, 422)
+end
+```
+
+For more information see [#462](https://github.com/intridea/grape/issues/462).

data/lib/grape.rb

@@ -6,6 +6,7 @@ require 'rack/accept'
 require 'rack/auth/basic'
 require 'rack/auth/digest/md5'
 require 'hashie'
+require 'set'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/ordered_hash'
 require 'active_support/core_ext/object/conversions'
@@ -16,6 +17,7 @@ require 'multi_json'
 require 'multi_xml'
 require 'virtus'
 require 'i18n'
+require 'thread'
 
 I18n.load_path << File.expand_path('../grape/locale/en.yml', __FILE__)
 

data/lib/grape/api.rb

@@ -9,6 +9,8 @@ module Grape
       attr_reader :endpoints, :instance, :routes, :route_set, :settings, :versions
       attr_writer :logger
 
+      LOCK = Mutex.new
+
       def logger(logger = nil)
         if logger
           @logger = logger
@@ -26,7 +28,7 @@ module Grape
       end
 
       def compile
-        @instance = new
+        @instance ||= new
       end
 
       def change!
@@ -34,7 +36,7 @@ module Grape
       end
 
       def call(env)
-        compile unless instance
+        LOCK.synchronize { compile } unless instance
         call!(env)
       end
 
@@ -199,6 +201,7 @@ module Grape
       #   @param [Block] block Execution block to handle the given exception.
       #   @param [Hash] options Options for the rescue usage.
       #   @option options [Boolean] :backtrace Include a backtrace in the rescue response.
+      #   @option options [Boolean] :rescue_subclasses Also rescue subclasses of exception classes
       #   @param [Proc] handler Execution proc to handle the given exception as an
       #     alternative to passing a block
       def rescue_from(*args, &block)
@@ -211,19 +214,12 @@ module Grape
         options = args.last.is_a?(Hash) ? args.pop : {}
         handler ||= proc { options[:with] } if options.has_key?(:with)
 
-        if handler
-          args.each do |arg|
-            imbue(:rescue_handlers, { arg => handler })
-          end
-        end
+        handler_type = !!options[:rescue_subclasses] ? :rescue_handlers : :base_only_rescue_handlers
+        imbue handler_type, Hash[args.map { |arg| [arg, handler] }]
 
         imbue(:rescue_options, options)
 
-        if args.include?(:all)
-          set(:rescue_all, true)
-        else
-          imbue(:rescued_errors, args)
-        end
+        set(:rescue_all, true) if args.include?(:all)
       end
 
       # Allows you to specify a default representation entity for a
@@ -274,11 +270,16 @@ module Grape
         if block_given? || new_mod
           mod = settings.peek[:helpers] || Module.new
           if new_mod
+            inject_api_helpers_to_mod(new_mod) if new_mod.is_a?(Helpers)
             mod.class_eval do
               include new_mod
             end
           end
-          mod.class_eval(&block) if block_given?
+          if block_given?
+            inject_api_helpers_to_mod(mod) do
+              mod.class_eval(&block)
+            end
+          end
           set(:helpers, mod)
         else
           mod = Module.new
@@ -324,11 +325,12 @@ module Grape
             app_settings.set :mount_path, mount_path
             app.inherit_settings(app_settings)
           end
-          endpoints << Grape::Endpoint.new(settings.clone, {
+          endpoints << Grape::Endpoint.new(
+            settings.clone,
             method: :any,
             path: path,
             app: app
-          })
+          )
         end
       end
 
@@ -360,6 +362,10 @@ module Grape
         imbue(:befores, [block])
       end
 
+      def before_validation(&block)
+        imbue(:before_validations, [block])
+      end
+
       def after_validation(&block)
         imbue(:after_validations, [block])
       end
@@ -510,14 +516,20 @@ module Grape
           e.options[:app].inherit_settings(other_stack) if e.options[:app].respond_to?(:inherit_settings, true)
         end
       end
+
+      def inject_api_helpers_to_mod(mod, &block)
+        mod.extend(Helpers)
+        yield if block_given?
+        mod.api_changed(self)
+      end
     end
 
     def initialize
       @route_set = Rack::Mount::RouteSet.new
+      add_head_not_allowed_methods_and_options_methods
       self.class.endpoints.each do |endpoint|
         endpoint.mount_in(@route_set)
       end
-      add_head_not_allowed_methods
       @route_set.freeze
     end
 
@@ -549,39 +561,78 @@ module Grape
     # with a list of HTTP methods that can be called. Also add a route that
     # will return an HTTP 405 response for any HTTP method that the resource
     # cannot handle.
-    def add_head_not_allowed_methods
-      allowed_methods = Hash.new { |h, k| h[k] = [] }
-      resources = self.class.endpoints.map do |endpoint|
-        if endpoint.options[:app] && endpoint.options[:app].respond_to?(:endpoints)
-          endpoint.options[:app].endpoints.map(&:routes)
-        else
-          endpoint.routes
+    def add_head_not_allowed_methods_and_options_methods
+      methods_per_path = {}
+      self.class.endpoints.each do |endpoint|
+        routes = endpoint.routes
+        routes.each do |route|
+          methods_per_path[route.route_path] ||= []
+          methods_per_path[route.route_path] << route.route_method
         end
       end
-      resources.flatten.each do |route|
-        allowed_methods[route.route_compiled] << route.route_method
-      end
-      allowed_methods.each do |path_info, methods|
-        if methods.include?('GET') && !methods.include?("HEAD") && !self.class.settings[:do_not_route_head]
-          methods = methods | ['HEAD']
-        end
-        allow_header = (["OPTIONS"] | methods).join(", ")
-        unless methods.include?("OPTIONS") || self.class.settings[:do_not_route_options]
-          @route_set.add_route(proc { [204, { 'Allow' => allow_header }, []] }, {
-            path_info: path_info,
-            request_method: "OPTIONS"
-          })
-        end
-        not_allowed_methods = %w(GET PUT POST DELETE PATCH HEAD) - methods
-        not_allowed_methods << "OPTIONS" if self.class.settings[:do_not_route_options]
-        not_allowed_methods.each do |bad_method|
-          @route_set.add_route(proc { [405, { 'Allow' => allow_header, 'Content-Type' => 'text/plain' }, []] }, {
-            path_info: path_info,
-            request_method: bad_method
-          })
+
+      # The paths we collected are prepared (cf. Path#prepare), so they
+      # contain already versioning information when using path versioning.
+      # Disable versioning so adding a route won't prepend versioning
+      # informations again.
+      without_versioning do
+        methods_per_path.each do |path, methods|
+          allowed_methods = methods.dup
+          unless self.class.settings[:do_not_route_head]
+            if allowed_methods.include?('GET')
+              allowed_methods = allowed_methods | ['HEAD']
+            end
+          end
+
+          allow_header = (['OPTIONS'] | allowed_methods).join(', ')
+          unless self.class.settings[:do_not_route_options]
+            unless allowed_methods.include?('OPTIONS')
+              self.class.options(path, {}) do
+                header 'Allow', allow_header
+                status 204
+                ''
+              end
+            end
+          end
+
+          not_allowed_methods = %w(GET PUT POST DELETE PATCH HEAD) - allowed_methods
+          not_allowed_methods << 'OPTIONS' if self.class.settings[:do_not_route_options]
+          self.class.route(not_allowed_methods, path) do
+            header 'Allow', allow_header
+            status 405
+            ''
+          end
         end
       end
     end
 
+    def without_versioning(&block)
+      self.class.settings.push(version: nil, version_options: nil)
+      yield
+      self.class.settings.pop
+    end
+
+    # This module extends user defined helpers
+    # to provide some API-specific functionality
+    module Helpers
+      attr_accessor :api
+      def params(name, &block)
+        @named_params ||= {}
+        @named_params.merge! name => block
+      end
+
+      def api_changed(new_api)
+        @api = new_api
+        process_named_params
+      end
+
+      protected
+
+      def process_named_params
+        if @named_params && @named_params.any?
+          api.imbue(:named_params, @named_params)
+        end
+      end
+    end
   end
 end

data/lib/grape/cookies.rb

@@ -1,6 +1,5 @@
 module Grape
   class Cookies
-
     def initialize
       @cookies = {}
       @send_cookies = {}
@@ -36,6 +35,5 @@ module Grape
       options = opts.merge(value: 'deleted', expires: Time.at(0))
       self.[]=(name, options)
     end
-
   end
 end

data/lib/grape/endpoint.rb

@@ -5,7 +5,7 @@ module Grape
   # from inside a `get`, `post`, etc.
   class Endpoint
     attr_accessor :block, :source, :options, :settings
-    attr_reader :env, :request
+    attr_reader :env, :request, :headers, :params
 
     class << self
       # @api private
@@ -80,7 +80,7 @@ module Grape
             route_set.add_route(self, {
               path_info: route.route_compiled,
               request_method: method,
-            }, { route_info: route })
+            },  route_info: route)
           end
         end
       end
@@ -146,6 +146,8 @@ module Grape
     end
 
     def call!(env)
+      extend helpers
+
       env['api.endpoint'] = self
       if options[:app]
         options[:app].call(env)
@@ -156,20 +158,22 @@ module Grape
       end
     end
 
-    # The parameters passed into the request as
-    # well as parsed from URL segments.
-    def params
-      @params ||= @request.params
-    end
-
     # A filtering method that will return a hash
     # consisting only of keys that have been declared by a
-    # `params` statement.
+    # `params` statement against the current/target endpoint or parent
+    # namespaces
     #
     # @param params [Hash] The initial hash to filter. Usually this will just be `params`
-    # @param options [Hash] Can pass `:include_missing` and `:stringify` options.
-    def declared(params, options = {}, declared_params = settings[:declared_params])
+    # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
+    # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
+    # you want only to return params declared against the current/target endpoint
+    def declared(params, options = {}, declared_params = nil)
       options[:include_missing] = true unless options.key?(:include_missing)
+      options[:include_parent_namespaces] = true unless options.key?(:include_parent_namespaces)
+      if declared_params.nil?
+        declared_params = !options[:include_parent_namespaces] ? settings[:declared_params] :
+          settings.gather(:declared_params)
+      end
 
       unless declared_params
         raise ArgumentError, "Tried to filter for declared parameters but none exist."
@@ -208,9 +212,10 @@ module Grape
     # end user with the specified message.
     #
     # @param message [String] The message to display.
-    # @param status [Integer] the HTTP Status Code. Defaults to 403.
-    def error!(message, status = 403)
-      throw :error, message: message, status: status
+    # @param status [Integer] the HTTP Status Code. Defaults to default_error_status, 500 if not set.
+    def error!(message, status = nil, headers = nil)
+      status = settings[:default_error_status] unless status
+      throw :error, message: message, status: status, headers: headers
     end
 
     # Redirect to a new url.
@@ -260,11 +265,6 @@ module Grape
       end
     end
 
-    # Retrieves all available request headers.
-    def headers
-      @headers ||= @request.headers
-    end
-
     # Set response content-type
     def content_type(val)
       header('Content-Type', val)
@@ -324,14 +324,16 @@ module Grape
                     end
       entity_class = options.delete(:with)
 
-      # auto-detect the entity from the first object in the collection
-      object_instance = object.respond_to?(:first) ? object.first : object
+      if entity_class.nil?
+        # entity class not explicitely defined, auto-detect from first object in the collection
+        object_instance = object.respond_to?(:first) ? object.first : object
 
-      object_instance.class.ancestors.each do |potential|
-        entity_class ||= (settings[:representations] || {})[potential]
-      end
+        object_instance.class.ancestors.each do |potential|
+          entity_class ||= (settings[:representations] || {})[potential]
+        end
 
-      entity_class ||= object_instance.class.const_get(:Entity) if object_instance.class.const_defined?(:Entity)
+        entity_class ||= object_instance.class.const_get(:Entity) if object_instance.class.const_defined?(:Entity) && object_instance.class.const_get(:Entity).respond_to?(:represent)
+      end
 
       root = options.delete(:root)
 
@@ -360,8 +362,6 @@ module Grape
       env["rack.routing_args"][:route_info]
     end
 
-    protected
-
     # Return the collection of endpoints within this endpoint.
     # This is the case when an Grape::API mounts another Grape::API.
     def endpoints
@@ -372,16 +372,22 @@ module Grape
       end
     end
 
+    protected
+
     def run(env)
       @env = env
       @header = {}
-      @request = Grape::Request.new(@env)
 
-      extend helpers
+      @request = Grape::Request.new(env)
+      @params = @request.params
+      @headers = @request.headers
+
       cookies.read(@request)
 
       run_filters befores
 
+      run_filters before_validations
+
       # Retieve validations from this namespace and all parent namespaces.
       validation_errors = []
       settings.gather(:validations).each do |validator|
@@ -411,13 +417,14 @@ module Grape
       b.use Rack::Head
       b.use Grape::Middleware::Error,
             format: settings[:format],
-            default_status: settings[:default_error_status] || 403,
+            content_types: settings[:content_types],
+            default_status: settings[:default_error_status] || 500,
             rescue_all: settings[:rescue_all],
-            rescued_errors: aggregate_setting(:rescued_errors),
             default_error_formatter: settings[:default_error_formatter],
             error_formatters: settings[:error_formatters],
             rescue_options: settings[:rescue_options],
-            rescue_handlers: merged_setting(:rescue_handlers)
+            rescue_handlers: merged_setting(:rescue_handlers),
+            base_only_rescue_handlers: merged_setting(:base_only_rescue_handlers)
 
       aggregate_setting(:middleware).each do |m|
         m = m.dup
@@ -429,15 +436,28 @@ module Grape
         end
       end
 
-      b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
-      b.use Rack::Auth::Digest::MD5, settings[:auth][:realm], settings[:auth][:opaque], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_digest
+      if settings[:auth]
+        auth_proc         = settings[:auth][:proc]
+        auth_proc_context = self
+        auth_middleware   = {
+          http_basic:   { class: Rack::Auth::Basic,       args: [settings[:auth][:realm]] },
+          http_digest:  { class: Rack::Auth::Digest::MD5, args: [settings[:auth][:realm], settings[:auth][:opaque]] }
+        }[settings[:auth][:type]]
+
+        # evaluate auth proc in context of endpoint
+        if auth_middleware
+          b.use auth_middleware[:class], *auth_middleware[:args] do |*args|
+            auth_proc_context.instance_exec(*args, &auth_proc)
+          end
+        end
+      end
 
       if settings[:version]
-        b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]), {
-          versions: settings[:version] ? settings[:version].flatten : nil,
-          version_options: settings[:version_options],
-          prefix: settings[:root_prefix]
-        }
+        b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]),
+              versions: settings[:version] ? settings[:version].flatten : nil,
+              version_options: settings[:version_options],
+              prefix: settings[:root_prefix]
+
       end
 
       b.use Grape::Middleware::Formatter,
@@ -480,6 +500,10 @@ module Grape
       aggregate_setting(:befores)
     end
 
+    def before_validations
+      aggregate_setting(:before_validations)
+    end
+
     def after_validations
       aggregate_setting(:after_validations)
     end