grape 1.1.0 → 1.2.5

data/UPGRADING.md

@@ -1,6 +1,117 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 1.2.4
+
+#### Headers in `error!` call
+
+Headers in `error!` will be merged with `headers` hash. If any header need to be cleared on `error!` call, make sure to move it to the `after` block.
+
+```ruby
+class SampleApi < Grape::API
+  before do
+    header 'X-Before-Header', 'before_call'
+  end
+
+  get 'ping' do
+    header 'X-App-Header', 'on_call'
+    error! :pong, 400, 'X-Error-Details' => 'Invalid token'
+  end
+end
+```
+**Former behaviour**
+```ruby
+  response.headers['X-Before-Header'] # => nil
+  response.headers['X-App-Header'] # => nil
+  response.headers['X-Error-Details'] # => Invalid token
+```
+
+**Current behaviour**
+```ruby
+  response.headers['X-Before-Header'] # => 'before_call'
+  response.headers['X-App-Header'] # => 'on_call'
+  response.headers['X-Error-Details'] # => Invalid token
+```
+
+### Upgrading to >= 1.2.1
+
+#### Obtaining the name of a mounted class
+
+In order to make obtaining the name of a mounted class simpler, we've delegated `.to_s` to `base.name`
+
+**Deprecated in 1.2.0**
+```ruby
+  payload[:endpoint].options[:for].name
+```
+**New**
+```ruby
+  payload[:endpoint].options[:for].to_s
+```
+
+### Upgrading to >= 1.2.0
+
+#### Changes in the Grape::API class
+
+##### Patching the class
+
+In an effort to make APIs re-mountable, The class `Grape::API` no longer refers to an API instance,
+rather, what used to be `Grape::API` is now `Grape::API::Instance` and `Grape::API` was replaced
+with a class that can contain several instances of `Grape::API`.
+
+This changes were done in such a way that no code-changes should be required.
+However, if experiencing problems, or relying on private methods and internal behaviour too deeply, it is possible to restore the prior behaviour by replacing the references from `Grape::API` to `Grape::API::Instance`.
+
+Note, this is particularly relevant if you are opening the class `Grape::API` for modification.
+
+**Deprecated**
+```ruby
+class Grape::API
+  # your patched logic
+  ...
+end
+```
+**New**
+```ruby
+class Grape::API::Instance
+  # your patched logic
+  ...
+end
+```
+
+##### `name` (and other caveats) of the mounted API
+
+After the patch, the mounted API is no longer a Named class inheriting from `Grape::API`, it is an anonymous class
+which inherit from `Grape::API::Instance`.
+What this means in practice, is:
+- Generally: you can access the named class from the instance calling the getter `base`.
+- In particular: If you need the `name`, you can use `base`.`name`
+
+**Deprecated**
+```ruby
+  payload[:endpoint].options[:for].name
+```
+**New**
+```ruby
+  payload[:endpoint].options[:for].base.name
+```
+
+#### Changes in rescue_from returned object
+
+Grape will now check the object returned from `rescue_from` and ensure that it is a `Rack::Response`. That makes sure response is valid and avoids exposing service information. Change any code that invoked `Rack::Response.new(...).finish` in a custom `rescue_from` block to `Rack::Response.new(...)` to comply with the validation.
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :all do |e|
+    # version prior to 1.2.0
+    Rack::Response.new([ e.message ], 500, { 'Content-type' => 'text/error' }).finish
+    # 1.2.0  version
+    Rack::Response.new([ e.message ], 500, { 'Content-type' => 'text/error' })
+  end
+end
+```
+
+See [#1757](https://github.com/ruby-grape/grape/pull/1757) and [#1776](https://github.com/ruby-grape/grape/pull/1776) for more information.
+
 ### Upgrading to >= 1.1.0
 
 #### Changes in HTTP Response Code for Unsupported Content Type

data/grape.gemspec

@@ -19,7 +19,9 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rack-accept'
   s.add_runtime_dependency 'virtus', '>= 1.0.0'
 
-  s.files         = Dir['**/*'].keep_if { |file| File.file?(file) }
+  s.files         = %w[CHANGELOG.md CONTRIBUTING.md README.md grape.png UPGRADING.md LICENSE]
+  s.files        += %w[grape.gemspec]
+  s.files        += Dir['lib/**/*']
   s.test_files    = Dir['spec/**/*']
   s.require_paths = ['lib']
 end

data/lib/grape.rb

@@ -34,7 +34,6 @@ module Grape
     autoload :Namespace
 
     autoload :Path
-
     autoload :Cookies
     autoload :Validations
     autoload :ErrorFormatter
@@ -55,105 +54,125 @@ module Grape
 
   module Exceptions
     extend ::ActiveSupport::Autoload
-    autoload :Base
-    autoload :Validation
-    autoload :ValidationArrayErrors
-    autoload :ValidationErrors
-    autoload :MissingVendorOption
-    autoload :MissingMimeType
-    autoload :MissingOption
-    autoload :InvalidFormatter
-    autoload :InvalidVersionerOption
-    autoload :UnknownValidator
-    autoload :UnknownOptions
-    autoload :UnknownParameter
-    autoload :InvalidWithOptionForRepresent
-    autoload :IncompatibleOptionValues
-    autoload :MissingGroupTypeError,          'grape/exceptions/missing_group_type'
-    autoload :UnsupportedGroupTypeError,      'grape/exceptions/unsupported_group_type'
-    autoload :InvalidMessageBody
-    autoload :InvalidAcceptHeader
-    autoload :InvalidVersionHeader
-    autoload :MethodNotAllowed
+    eager_autoload do
+      autoload :Base
+      autoload :Validation
+      autoload :ValidationArrayErrors
+      autoload :ValidationErrors
+      autoload :MissingVendorOption
+      autoload :MissingMimeType
+      autoload :MissingOption
+      autoload :InvalidFormatter
+      autoload :InvalidVersionerOption
+      autoload :UnknownValidator
+      autoload :UnknownOptions
+      autoload :UnknownParameter
+      autoload :InvalidWithOptionForRepresent
+      autoload :IncompatibleOptionValues
+      autoload :MissingGroupTypeError,          'grape/exceptions/missing_group_type'
+      autoload :UnsupportedGroupTypeError,      'grape/exceptions/unsupported_group_type'
+      autoload :InvalidMessageBody
+      autoload :InvalidAcceptHeader
+      autoload :InvalidVersionHeader
+      autoload :MethodNotAllowed
+      autoload :InvalidResponse
+    end
   end
 
   module Extensions
     extend ::ActiveSupport::Autoload
-
-    autoload :DeepMergeableHash
-    autoload :DeepSymbolizeHash
-    autoload :DeepHashWithIndifferentAccess
-    autoload :Hash
-
+    eager_autoload do
+      autoload :DeepMergeableHash
+      autoload :DeepSymbolizeHash
+      autoload :DeepHashWithIndifferentAccess
+      autoload :Hash
+    end
     module ActiveSupport
       extend ::ActiveSupport::Autoload
-
-      autoload :HashWithIndifferentAccess
+      eager_autoload do
+        autoload :HashWithIndifferentAccess
+      end
     end
 
     module Hashie
       extend ::ActiveSupport::Autoload
-
-      autoload :Mash
+      eager_autoload do
+        autoload :Mash
+      end
     end
   end
 
   module Middleware
     extend ::ActiveSupport::Autoload
-    autoload :Base
-    autoload :Versioner
-    autoload :Formatter
-    autoload :Error
-    autoload :Globals
-    autoload :Stack
+    eager_autoload do
+      autoload :Base
+      autoload :Versioner
+      autoload :Formatter
+      autoload :Error
+      autoload :Globals
+      autoload :Stack
+      autoload :Helpers
+    end
 
     module Auth
       extend ::ActiveSupport::Autoload
-      autoload :Base
-      autoload :DSL
-      autoload :StrategyInfo
-      autoload :Strategies
+      eager_autoload do
+        autoload :Base
+        autoload :DSL
+        autoload :StrategyInfo
+        autoload :Strategies
+      end
     end
 
     module Versioner
       extend ::ActiveSupport::Autoload
-      autoload :Path
-      autoload :Header
-      autoload :Param
-      autoload :AcceptVersionHeader
+      eager_autoload do
+        autoload :Path
+        autoload :Header
+        autoload :Param
+        autoload :AcceptVersionHeader
+      end
     end
   end
 
   module Util
     extend ::ActiveSupport::Autoload
-    autoload :InheritableValues
-    autoload :StackableValues
-    autoload :ReverseStackableValues
-    autoload :InheritableSetting
-    autoload :StrictHashConfiguration
-    autoload :Registrable
+    eager_autoload do
+      autoload :InheritableValues
+      autoload :StackableValues
+      autoload :ReverseStackableValues
+      autoload :InheritableSetting
+      autoload :StrictHashConfiguration
+      autoload :Registrable
+    end
   end
 
   module ErrorFormatter
     extend ::ActiveSupport::Autoload
-    autoload :Base
-    autoload :Json
-    autoload :Txt
-    autoload :Xml
+    eager_autoload do
+      autoload :Base
+      autoload :Json
+      autoload :Txt
+      autoload :Xml
+    end
   end
 
   module Formatter
     extend ::ActiveSupport::Autoload
-    autoload :Json
-    autoload :SerializableHash
-    autoload :Txt
-    autoload :Xml
+    eager_autoload do
+      autoload :Json
+      autoload :SerializableHash
+      autoload :Txt
+      autoload :Xml
+    end
   end
 
   module Parser
     extend ::ActiveSupport::Autoload
-    autoload :Json
-    autoload :Xml
+    eager_autoload do
+      autoload :Json
+      autoload :Xml
+    end
   end
 
   module DSL
@@ -177,26 +196,38 @@ module Grape
 
   class API
     extend ::ActiveSupport::Autoload
-    autoload :Helpers
+    eager_autoload do
+      autoload :Helpers
+    end
   end
 
   module Presenters
     extend ::ActiveSupport::Autoload
-    autoload :Presenter
+    eager_autoload do
+      autoload :Presenter
+    end
   end
 
   module ServeFile
     extend ::ActiveSupport::Autoload
-    autoload :FileResponse
-    autoload :FileBody
-    autoload :SendfileResponse
+    eager_autoload do
+      autoload :FileResponse
+      autoload :FileBody
+      autoload :SendfileResponse
+    end
   end
 end
 
+require 'grape/config'
 require 'grape/util/content_types'
+require 'grape/util/lazy_value'
+require 'grape/util/lazy_block'
+require 'grape/util/endpoint_configuration'
 
 require 'grape/validations/validators/base'
 require 'grape/validations/attributes_iterator'
+require 'grape/validations/single_attribute_iterator'
+require 'grape/validations/multiple_attributes_iterator'
 require 'grape/validations/validators/allow_blank'
 require 'grape/validations/validators/as'
 require 'grape/validations/validators/at_least_one_of'
@@ -206,6 +237,7 @@ require 'grape/validations/validators/exactly_one_of'
 require 'grape/validations/validators/mutual_exclusion'
 require 'grape/validations/validators/presence'
 require 'grape/validations/validators/regexp'
+require 'grape/validations/validators/same_as'
 require 'grape/validations/validators/values'
 require 'grape/validations/validators/except_values'
 require 'grape/validations/params_scope'

data/lib/grape/api.rb

@@ -1,233 +1,194 @@
 require 'grape/router'
+require 'grape/api/instance'
 
 module Grape
   # The API class is the primary entry point for creating Grape APIs. Users
   # should subclass this class in order to build an API.
   class API
-    include Grape::DSL::API
+    # Class methods that we want to call on the API rather than on the API object
+    NON_OVERRIDABLE = (Class.new.methods + %i[call call! configuration compile!]).freeze
 
     class << self
-      attr_reader :instance
+      attr_accessor :base_instance, :instances
 
-      # A class-level lock to ensure the API is not compiled by multiple
-      # threads simultaneously within the same process.
-      LOCK = Mutex.new
+      # Rather than initializing an object of type Grape::API, create an object of type Instance
+      def new(*args, &block)
+        base_instance.new(*args, &block)
+      end
 
-      # Clears all defined routes, endpoints, etc., on this API.
-      def reset!
-        reset_endpoints!
-        reset_routes!
-        reset_validations!
+      # When inherited, will create a list of all instances (times the API was mounted)
+      # It will listen to the setup required to mount that endpoint, and replicate it on any new instance
+      def inherited(api, base_instance_parent = Grape::API::Instance)
+        api.initial_setup(base_instance_parent)
+        api.override_all_methods!
+        make_inheritable(api)
       end
 
-      # Parses the API's definition and compiles it into an instance of
-      # Grape::API.
-      def compile
-        @instance ||= new
+      # Initialize the instance variables on the remountable class, and the base_instance
+      # an instance that will be used to create the set up but will not be mounted
+      def initial_setup(base_instance_parent)
+        @instances = []
+        @setup = []
+        @base_parent = base_instance_parent
+        @base_instance = mount_instance
       end
 
-      # Wipe the compiled API so we can recompile after changes were made.
-      def change!
-        @instance = nil
+      # Redefines all methods so that are forwarded to add_setup and be recorded
+      def override_all_methods!
+        (base_instance.methods - NON_OVERRIDABLE).each do |method_override|
+          define_singleton_method(method_override) do |*args, &block|
+            add_setup(method_override, *args, &block)
+          end
+        end
+      end
+
+      # Configure an API from the outside. If a block is given, it'll pass a
+      # configuration hash to the block which you can use to configure your
+      # API. If no block is given, returns the configuration hash.
+      # The configuration set here is accessible from inside an API with
+      # `configuration` as normal.
+      def configure
+        config = @base_instance.configuration
+        if block_given?
+          yield config
+          self
+        else
+          config
+        end
       end
 
       # This is the interface point between Rack and Grape; it accepts a request
       # from Rack and ultimately returns an array of three values: the status,
       # the headers, and the body. See [the rack specification]
       # (http://www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.
-      def call(env)
-        LOCK.synchronize { compile } unless instance
-        call!(env)
+      # NOTE: This will only be called on an API directly mounted on RACK
+      def call(*args, &block)
+        instance_for_rack.call(*args, &block)
       end
 
-      # A non-synchronized version of ::call.
-      def call!(env)
-        instance.call(env)
+      # Allows an API to itself be inheritable:
+      def make_inheritable(api)
+        # When a child API inherits from a parent API.
+        def api.inherited(child_api)
+          # The instances of the child API inherit from the instances of the parent API
+          Grape::API.inherited(child_api, base_instance)
+        end
       end
 
-      # (see #cascade?)
-      def cascade(value = nil)
-        if value.nil?
-          inheritable_setting.namespace_inheritable.keys.include?(:cascade) ? !namespace_inheritable(:cascade).nil? : true
+      # Alleviates problems with autoloading by tring to search for the constant
+      def const_missing(*args)
+        if base_instance.const_defined?(*args)
+          base_instance.const_get(*args)
         else
-          namespace_inheritable(:cascade, value)
+          super
         end
       end
 
-      # see Grape::Router#recognize_path
-      def recognize_path(path)
-        LOCK.synchronize { compile } unless instance
-        instance.router.recognize_path(path)
+      # The remountable class can have a configuration hash to provide some dynamic class-level variables.
+      # For instance, a descripcion could be done using: `desc configuration[:description]` if it may vary
+      # depending on where the endpoint is mounted. Use with care, if you find yourself using configuration
+      # too much, you may actually want to provide a new API rather than remount it.
+      def mount_instance(opts = {})
+        instance = Class.new(@base_parent)
+        instance.configuration = Grape::Util::EndpointConfiguration.new(opts[:configuration] || {})
+        instance.base = self
+        replay_setup_on(instance)
+        instance
       end
 
-      protected
+      # Replays the set up to produce an API as defined in this class, can be called
+      # on classes that inherit from Grape::API
+      def replay_setup_on(instance)
+        @setup.each do |setup_step|
+          replay_step_on(instance, setup_step)
+        end
+      end
 
-      def prepare_routes
-        endpoints.map(&:routes).flatten
+      def respond_to?(method, include_private = false)
+        super(method, include_private) || base_instance.respond_to?(method, include_private)
       end
 
-      # Execute first the provided block, then each of the
-      # block passed in. Allows for simple 'before' setups
-      # of settings stack pushes.
-      def nest(*blocks, &block)
-        blocks.reject!(&:nil?)
-        if blocks.any?
-          instance_eval(&block) if block_given?
-          blocks.each { |b| instance_eval(&b) }
-          reset_validations!
+      def respond_to_missing?(method, include_private = false)
+        base_instance.respond_to?(method, include_private)
+      end
+
+      def method_missing(method, *args, &block)
+        # If there's a missing method, it may be defined on the base_instance instead.
+        if respond_to_missing?(method)
+          base_instance.send(method, *args, &block)
         else
-          instance_eval(&block)
+          super
         end
       end
 
-      def inherited(subclass)
-        subclass.reset!
-        subclass.logger = logger.clone
+      def compile!
+        require 'grape/eager_load'
+        instance_for_rack.compile! # See API::Instance.compile!
       end
 
-      def inherit_settings(other_settings)
-        top_level_setting.inherit_from other_settings.point_in_time_copy
+      private
 
-        # Propagate any inherited params down to our endpoints, and reset any
-        # compiled routes.
-        endpoints.each do |e|
-          e.inherit_settings(top_level_setting.namespace_stackable)
-          e.reset_routes!
+      def instance_for_rack
+        if never_mounted?
+          base_instance
+        else
+          mounted_instances.first
         end
-
-        reset_routes!
       end
-    end
-
-    attr_reader :router
 
-    # Builds the routes from the defined endpoints, effectively compiling
-    # this API into a usable form.
-    def initialize
-      @router = Router.new
-      add_head_not_allowed_methods_and_options_methods
-      self.class.endpoints.each do |endpoint|
-        endpoint.mount_in(@router)
+      # Adds a new stage to the set up require to get a Grape::API up and running
+      def add_setup(method, *args, &block)
+        setup_step = { method: method, args: args, block: block }
+        @setup << setup_step
+        last_response = nil
+        @instances.each do |instance|
+          last_response = replay_step_on(instance, setup_step)
+        end
+        last_response
       end
 
-      @router.compile!
-      @router.freeze
-    end
-
-    # Handle a request. See Rack documentation for what `env` is.
-    def call(env)
-      result = @router.call(env)
-      result[1].delete(Grape::Http::Headers::X_CASCADE) unless cascade?
-      result
-    end
-
-    # Some requests may return a HTTP 404 error if grape cannot find a matching
-    # route. In this case, Grape::Router adds a X-Cascade header to the response
-    # and sets it to 'pass', indicating to grape's parents they should keep
-    # looking for a matching route on other resources.
-    #
-    # In some applications (e.g. mounting grape on rails), one might need to trap
-    # errors from reaching upstream. This is effectivelly done by unsetting
-    # X-Cascade. Default :cascade is true.
-    def cascade?
-      return self.class.namespace_inheritable(:cascade) if self.class.inheritable_setting.namespace_inheritable.keys.include?(:cascade)
-      return self.class.namespace_inheritable(:version_options)[:cascade] if self.class.namespace_inheritable(:version_options) && self.class.namespace_inheritable(:version_options).key?(:cascade)
-      true
-    end
-
-    reset!
-
-    private
-
-    # For every resource add a 'OPTIONS' route that returns an HTTP 204 response
-    # 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_and_options_methods
-      routes_map = {}
-
-      self.class.endpoints.each do |endpoint|
-        routes = endpoint.routes
-        routes.each do |route|
-          # using the :any shorthand produces [nil] for route methods, substitute all manually
-          route_key = route.pattern.to_regexp
-          routes_map[route_key] ||= {}
-          route_settings = routes_map[route_key]
-          route_settings[:pattern] = route.pattern
-          route_settings[:requirements] = route.requirements
-          route_settings[:path] = route.origin
-          route_settings[:methods] ||= []
-          route_settings[:methods] << route.request_method
-          route_settings[:endpoint] = route.app
-
-          # using the :any shorthand produces [nil] for route methods, substitute all manually
-          route_settings[:methods] = %w[GET PUT POST DELETE PATCH HEAD OPTIONS] if route_settings[:methods].include?('*')
+      def replay_step_on(instance, setup_step)
+        return if skip_immediate_run?(instance, setup_step[:args])
+        args = evaluate_arguments(instance.configuration, *setup_step[:args])
+        response = instance.send(setup_step[:method], *args, &setup_step[:block])
+        if skip_immediate_run?(instance, [response])
+          response
+        else
+          evaluate_arguments(instance.configuration, response).first
         end
       end
 
-      # 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_root_prefix do
-        without_versioning do
-          routes_map.each do |_, config|
-            methods = config[:methods]
-            allowed_methods = methods.dup
-
-            unless self.class.namespace_inheritable(:do_not_route_head)
-              allowed_methods |= [Grape::Http::Headers::HEAD] if allowed_methods.include?(Grape::Http::Headers::GET)
-            end
-
-            allow_header = (self.class.namespace_inheritable(:do_not_route_options) ? allowed_methods : [Grape::Http::Headers::OPTIONS] | allowed_methods).join(', ')
+      # Skips steps that contain arguments to be lazily executed (on re-mount time)
+      def skip_immediate_run?(instance, args)
+        instance.base_instance? &&
+          (any_lazy?(args) || args.any? { |arg| arg.is_a?(Hash) && any_lazy?(arg.values) })
+      end
 
-            unless self.class.namespace_inheritable(:do_not_route_options) || allowed_methods.include?(Grape::Http::Headers::OPTIONS)
-              config[:endpoint].options[:options_route_enabled] = true
-            end
+      def any_lazy?(args)
+        args.any? { |argument| argument.respond_to?(:lazy?) && argument.lazy? }
+      end
 
-            attributes = config.merge(allowed_methods: allowed_methods, allow_header: allow_header)
-            generate_not_allowed_method(config[:pattern], attributes)
+      def evaluate_arguments(configuration, *args)
+        args.map do |argument|
+          if argument.respond_to?(:lazy?) && argument.lazy?
+            argument.evaluate_from(configuration)
+          elsif argument.is_a?(Hash)
+            argument.map { |key, value| [key, evaluate_arguments(configuration, value).first] }.to_h
+          elsif argument.is_a?(Array)
+            evaluate_arguments(configuration, *argument)
+          else
+            argument
           end
         end
       end
-    end
-
-    # Generate a route that returns an HTTP 405 response for a user defined
-    # path on methods not specified
-    def generate_not_allowed_method(pattern, allowed_methods: [], **attributes)
-      not_allowed_methods = %w[GET PUT POST DELETE PATCH HEAD] - allowed_methods
-      not_allowed_methods << Grape::Http::Headers::OPTIONS if self.class.namespace_inheritable(:do_not_route_options)
 
-      return if not_allowed_methods.empty?
-
-      @router.associate_routes(pattern, not_allowed_methods: not_allowed_methods, **attributes)
-    end
-
-    # Allows definition of endpoints that ignore the versioning configuration
-    # used by the rest of your API.
-    def without_versioning(&_block)
-      old_version = self.class.namespace_inheritable(:version)
-      old_version_options = self.class.namespace_inheritable(:version_options)
-
-      self.class.namespace_inheritable_to_nil(:version)
-      self.class.namespace_inheritable_to_nil(:version_options)
-
-      yield
-
-      self.class.namespace_inheritable(:version, old_version)
-      self.class.namespace_inheritable(:version_options, old_version_options)
-    end
-
-    # Allows definition of endpoints that ignore the root prefix used by the
-    # rest of your API.
-    def without_root_prefix(&_block)
-      old_prefix = self.class.namespace_inheritable(:root_prefix)
-
-      self.class.namespace_inheritable_to_nil(:root_prefix)
-
-      yield
+      def never_mounted?
+        mounted_instances.empty?
+      end
 
-      self.class.namespace_inheritable(:root_prefix, old_prefix)
+      def mounted_instances
+        instances - [base_instance]
+      end
     end
   end
 end