grape 0.12.0 → 0.14.0

data/RELEASING.md

@@ -12,12 +12,12 @@ bundle install
 rake
 ```
 
-Check that the last build succeeded in [Travis CI](https://travis-ci.org/intridea/grape) for all supported platforms.
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/ruby-grape/grape) for all supported platforms.
 
-Those with r/w permissions to the [master Intridea repository](https://github.com/intridea/grape) generally have large Grape-based projects. Point one to Grape HEAD and run all your API tests to catch any obvious regressions.
+Those with r/w permissions to the [master Grape repository](https://github.com/ruby-grape/grape) generally have large Grape-based projects. Point one to Grape HEAD and run all your API tests to catch any obvious regressions.
 
 ```
-gem grape, github: 'intridea/grape'
+gem grape, github: 'ruby-grape/grape'
 ```
 
 Increment the version, modify [lib/grape/version.rb](lib/grape/version.rb).
@@ -69,7 +69,7 @@ Modify the "Stable Release" section in [README.md](README.md). Change the text t
 ## Stable Release
 
 You're reading the documentation for the next release of Grape, which should be 0.6.1.
-The current stable release is [0.6.0](https://github.com/intridea/grape/blob/v0.6.0/README.md).
+The current stable release is [0.6.0](https://github.com/ruby-grape/grape/blob/v0.6.0/README.md).
 ```
 
 Add the next release to [CHANGELOG.md](CHANGELOG.md).
@@ -81,11 +81,19 @@ Next Release
 * Your contribution here.
 ```
 
+Bump the minor version in lib/grape/version.rb.
+
+```ruby
+module Grape
+  VERSION = '0.6.1'
+end
+```
+
 Comit your changes.
 
 ```
-git add CHANGELOG.md README.md
-git commit -m "Preparing for next release."
+git add CHANGELOG.md README.md lib/grape/version.rb
+git commit -m "Preparing for next development iteration, 0.6.1."
 git push origin master
 ```
 

data/Rakefile

@@ -17,52 +17,49 @@ end
 task :spec
 
 require 'rainbow/ext/string' unless String.respond_to?(:color)
+
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
 task default: [:rubocop, :spec]
 
-begin
-  require 'yard'
-  DOC_FILES = ['lib/**/*.rb', 'README.md']
+require 'yard'
+DOC_FILES = ['lib/**/*.rb', 'README.md']
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = DOC_FILES
+end
 
-  YARD::Rake::YardocTask.new(:doc) do |t|
+namespace :doc do
+  YARD::Rake::YardocTask.new(:pages) do |t|
     t.files   = DOC_FILES
+    t.options = ['-o', '../grape.doc/docs']
   end
 
-  namespace :doc do
-    YARD::Rake::YardocTask.new(:pages) do |t|
-      t.files   = DOC_FILES
-      t.options = ['-o', '../grape.doc/docs']
-    end
-
-    namespace :pages do
-      desc 'Check out gh-pages.'
-      task :checkout do
-        dir = File.dirname(__FILE__) + '/../grape.doc'
-        unless Dir.exist?(dir)
-          Dir.mkdir(dir)
-          Dir.chdir(dir) do
-            system('git init')
-            system('git remote add origin git@github.com:intridea/grape.git')
-            system('git pull')
-            system('git checkout gh-pages')
-          end
+  namespace :pages do
+    desc 'Check out gh-pages.'
+    task :checkout do
+      dir = File.dirname(__FILE__) + '/../grape.doc'
+      unless Dir.exist?(dir)
+        Dir.mkdir(dir)
+        Dir.chdir(dir) do
+          system('git init')
+          system('git remote add origin git@github.com:ruby-grape/grape.git')
+          system('git pull')
+          system('git checkout gh-pages')
         end
       end
+    end
 
-      desc 'Generate and publish YARD docs to GitHub pages.'
-      task publish: ['doc:pages:checkout', 'doc:pages'] do
-        Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
-          system('git checkout gh-pages')
-          system('git add .')
-          system('git add -u')
-          system("git commit -m 'Generating docs for version #{Grape::VERSION}.'")
-          system('git push origin gh-pages')
-        end
+    desc 'Generate and publish YARD docs to GitHub pages.'
+    task publish: ['doc:pages:checkout', 'doc:pages'] do
+      Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
+        system('git checkout gh-pages')
+        system('git add .')
+        system('git add -u')
+        system("git commit -m 'Generating docs for version #{Grape::VERSION}.'")
+        system('git push origin gh-pages')
       end
     end
   end
-rescue LoadError
-  puts 'You need to install YARD.'
 end

data/UPGRADING.md

@@ -1,6 +1,37 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 0.14.0
+
+#### Changes to availability of DSL methods in filters
+
+The `#declared` method of the route DSL is no longer available in the `before` filter.  Using `declared` in a `before` filter will now raise `Grape::DSL::InsideRoute::MethodNotYetAvailable`.
+
+See [#1074](https://github.com/ruby-grape/grape/issues/1074) for discussion of the issue.
+
+#### Changes to header versioning and invalid header version handling
+
+Identical endpoints with different versions now work correctly. A regression introduced in Grape 0.11.0 caused all but the first-mounted version for such an endpoint to wrongly throw an `InvalidAcceptHeader`. As a side effect, requests with a correct vendor but invalid version can no longer be rescued from a `rescue_from` block.
+
+See [#1114](https://github.com/ruby-grape/grape/pull/1114) for more information.
+
+#### Bypasses formatters when status code indicates no content
+
+To be consistent with rack and it's handling of standard responses
+associated with no content, both default and custom formatters will now
+be bypassed when processing responses for status codes defined [by rack](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
+
+See [#1190](https://github.com/ruby-grape/grape/pull/1190) for more information.
+
+#### Redirects respond as plain text with message
+
+`#redirect` now uses `text/plain` regardless of whether that format has
+been enabled. This prevents formatters from attempting to serialize the
+message body and allows for a descriptive message body to be provided - and
+optionally overridden - that better fulfills the theme of the HTTP spec.
+
+See [#1194](https://github.com/ruby-grape/grape/pull/1194) for more information.
+
 ### Upgrading to >= 0.12.0
 
 #### Changes in middleware
@@ -29,13 +60,13 @@ class CacheBusterMiddleware < Grape::Middleware::Base
 end
 ```
 
-See [#1029](https://github.com/intridea/grape/pull/1029) for more information.
+See [#1029](https://github.com/ruby-grape/grape/pull/1029) for more information.
 
 #### Changes in present
 
 Using `present` with objects that responded to `merge` would cause early evaluation of the represented object, with unexpected side-effects, such as missing parameters or environment within rendering code. Grape now only merges represented objects with a previously rendered body, usually when multiple `present` calls are made in the same route.
 
-See [grape-with-roar#5](https://github.com/dblock/grape-with-roar/issues/5) and [#1023](https://github.com/intridea/grape/issues/1023).
+See [grape-with-roar#5](https://github.com/dblock/grape-with-roar/issues/5) and [#1023](https://github.com/ruby-grape/grape/issues/1023).
 
 #### Changes to regexp validator
 
@@ -47,7 +78,7 @@ params do
 end
 ```
 
-See [#957](https://github.com/intridea/grape/pull/957) for more information.
+See [#957](https://github.com/ruby-grape/grape/pull/957) for more information.
 
 #### Replace error_response with error! in rescue_from blocks
 
@@ -88,11 +119,11 @@ Rack::Response.new([ e.message ], 500, { "Content-type" => "text/error" }).finis
 error!(e)
 ```
 
-See [#889](https://github.com/intridea/grape/issues/889) for more information.
+See [#889](https://github.com/ruby-grape/grape/issues/889) for more information.
 
 #### Changes to routes when using `format`
 
-Version 0.10.0 has introduced a change via [#809](https://github.com/intridea/grape/pull/809) whereas routes no longer got file-type suffixes added if you declared a single API `format`. This has been reverted, it's now again possible to call API with proper suffix when single `format` is defined:
+Version 0.10.0 has introduced a change via [#809](https://github.com/ruby-grape/grape/pull/809) whereas routes no longer got file-type suffixes added if you declared a single API `format`. This has been reverted, it's now again possible to call API with proper suffix when single `format` is defined:
 
 ```ruby
 class API < Grape::API
@@ -108,7 +139,7 @@ Will respond with JSON to `/hello` **and** `/hello.json`.
 
 Will respond with 404 to `/hello.xml`, `/hello.txt` etc.
 
-See the [#1001](https://github.com/intridea/grape/pull/1001) and [#914](https://github.com/intridea/grape/issues/914) for more info.
+See the [#1001](https://github.com/ruby-grape/grape/pull/1001) and [#914](https://github.com/ruby-grape/grape/issues/914) for more info.
 
 ### Upgrading to >= 0.11.0
 
@@ -120,20 +151,20 @@ Grape now supports, but doesn't require Rack 1.6.0. If you encounter an issue wi
 gem 'rack', '~> 1.6.0'
 ```
 
-See [#559](https://github.com/intridea/grape/issues/559) for more information.
+See [#559](https://github.com/ruby-grape/grape/issues/559) for more information.
 
 #### Removed route_info
 
 Key route_info is excluded from params.
 
-See [#879](https://github.com/intridea/grape/pull/879) for more information.
+See [#879](https://github.com/ruby-grape/grape/pull/879) for more information.
 
 
 #### Fix callbacks within a version block
 
 Callbacks defined in a version block are only called for the routes defined in that block. This was a regression introduced in Grape 0.10.0, and is fixed in this version.
 
-See [#901](https://github.com/intridea/grape/pull/901) for more information.
+See [#901](https://github.com/ruby-grape/grape/pull/901) for more information.
 
 
 #### Make type of group of parameters required
@@ -141,7 +172,7 @@ See [#901](https://github.com/intridea/grape/pull/901) for more information.
 Groups of parameters now require their type to be set explicitly as Array or Hash.
 Not setting the type now results in MissingGroupTypeError, unsupported type will raise UnsupportedTypeError.
 
-See [#886](https://github.com/intridea/grape/pull/886) for more information.
+See [#886](https://github.com/ruby-grape/grape/pull/886) for more information.
 
 ### Upgrading to >= 0.10.1
 
@@ -149,7 +180,7 @@ See [#886](https://github.com/intridea/grape/pull/886) for more information.
 
 Attributes with `nil` values or with values that evaluate to `false` are no longer considered *missing* and will be returned when `include_missing` is set to `false`.
 
-See [#864](https://github.com/intridea/grape/pull/864) for more information.
+See [#864](https://github.com/ruby-grape/grape/pull/864) for more information.
 
 ### Upgrading to >= 0.10.0
 
@@ -284,13 +315,13 @@ get do
 end
 ```
 
-For more information see [#836](https://github.com/intridea/grape/issues/836).
+For more information see [#836](https://github.com/ruby-grape/grape/issues/836).
 
 #### Changes to Custom Validators
 
 To implement a custom validator, you need to inherit from `Grape::Validations::Base` instead of `Grape::Validations::Validator`.
 
-For more information see [Custom Validators](https://github.com/intridea/grape#custom-validators) in the documentation.
+For more information see [Custom Validators](https://github.com/ruby-grape/grape#custom-validators) in the documentation.
 
 #### Changes to Raising Grape::Exceptions::Validation
 
@@ -337,7 +368,7 @@ class API < Grape::API
 end
 ```
 
-See the [the updated API Formats documentation](https://github.com/intridea/grape#api-formats) and [#809](https://github.com/intridea/grape/pull/809) for more info.
+See the [the updated API Formats documentation](https://github.com/ruby-grape/grape#api-formats) and [#809](https://github.com/ruby-grape/grape/pull/809) for more info.
 
 #### Changes to Evaluation of Permitted Parameter Values
 
@@ -357,7 +388,7 @@ params do
 end
 ```
 
-See [#801](https://github.com/intridea/grape/issues/801) for more information.
+See [#801](https://github.com/ruby-grape/grape/issues/801) for more information.
 
 #### Changes to version
 
@@ -389,7 +420,7 @@ end
 
 when making a API call `GET /foo/v2/1`, the API would set instance variable `@output` to `hello1-v2`
 
-See [#898](https://github.com/intridea/grape/issues/898) for more information.
+See [#898](https://github.com/ruby-grape/grape/issues/898) for more information.
 
 
 ### Upgrading to >= 0.9.0
@@ -422,10 +453,10 @@ As replacement can be used
 * `Grape::Middleware::Auth::Digest` => [`Rack::Auth::Digest::MD5`](https://github.com/rack/rack/blob/master/lib/rack/auth/digest/md5.rb)
 * `Grape::Middleware::Auth::OAuth2` => [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2)
 
-If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/intridea/grape/tree/v0.7.0/lib/grape/middleware/auth)
+If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/ruby-grape/grape/tree/v0.7.0/lib/grape/middleware/auth)
 and host these files within your application
 
-See [#703](https://github.com/intridea/Grape/pull/703) for more information.
+See [#703](https://github.com/ruby-grape/Grape/pull/703) for more information.
 
 ### Upgrading to >= 0.7.0
 
@@ -462,7 +493,7 @@ rescue_from ParentError, rescue_subclasses: false do |e|
 end
 ```
 
-See [#544](https://github.com/intridea/grape/pull/544) for more information.
+See [#544](https://github.com/ruby-grape/grape/pull/544) for more information.
 
 
 #### Changes in the Default HTTP Status Code
@@ -485,7 +516,7 @@ You may also use `default_error_status` to change the global default.
 default_error_status 400
 ```
 
-See [#525](https://github.com/intridea/Grape/pull/525) for more information.
+See [#525](https://github.com/ruby-grape/Grape/pull/525) for more information.
 
 
 #### Changes in Parameter Declaration and Validation
@@ -502,7 +533,7 @@ params do
 end
 ```
 
-This caused the ambiguity and unexpected errors described in [#543](https://github.com/intridea/Grape/issues/543).
+This caused the ambiguity and unexpected errors described in [#543](https://github.com/ruby-grape/Grape/issues/543).
 
 In Grape 0.7.0, 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).
 
@@ -530,7 +561,7 @@ params do
 end
 ```
 
-See [#545](https://github.com/intridea/Grape/pull/545) for more information.
+See [#545](https://github.com/ruby-grape/Grape/pull/545) for more information.
 
 
 ### Upgrading to 0.6.0
@@ -547,4 +578,4 @@ rescue_from Grape::Exceptions::Validations do |e|
 end
 ```
 
-For more information see [#462](https://github.com/intridea/grape/issues/462).
+For more information see [#462](https://github.com/ruby-grape/grape/issues/462).

data/benchmark/simple.rb

@@ -0,0 +1,27 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'grape'
+require 'benchmark/ips'
+
+class API < Grape::API
+  prefix :api
+  version 'v1', using: :path
+  get '/' do
+    'hello'
+  end
+end
+
+options = {
+  method: 'GET'
+}
+
+env = Rack::MockRequest.env_for('/api/v1', options)
+
+10.times do |i|
+  env["HTTP_HEADER#{i}"] = '123'
+end
+
+Benchmark.ips do |ips|
+  ips.report('simple') do
+    API.call env
+  end
+end

data/gemfiles/rack_1.5.2.gemfile

@@ -0,0 +1,13 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rack', '1.5.2'
+
+group :development, :test do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+end
+
+gemspec path: '../'

data/gemfiles/rails_3.gemfile

@@ -3,12 +3,12 @@
 source 'https://rubygems.org'
 
 gem 'rails', '3.2.19'
+gem 'rack-cache', '<= 1.2'
 
 group :development, :test do
-  gem 'rubocop', '~> 0.31.0'
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
 end
 
-gemspec :path => '../'
+gemspec path: '../'

data/gemfiles/rails_4.gemfile

@@ -5,10 +5,9 @@ source 'https://rubygems.org'
 gem 'rails', '4.1.6'
 
 group :development, :test do
-  gem 'rubocop', '~> 0.31.0'
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
 end
 
-gemspec :path => '../'
+gemspec path: '../'

data/grape.gemspec

@@ -7,13 +7,11 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ['Michael Bleigh']
   s.email       = ['michael@intridea.com']
-  s.homepage    = 'https://github.com/intridea/grape'
+  s.homepage    = 'https://github.com/ruby-grape/grape'
   s.summary     = 'A simple Ruby framework for building REST-like APIs.'
   s.description = 'A Ruby framework for rapid API development with great conventions.'
   s.license     = 'MIT'
 
-  s.rubyforge_project = 'grape'
-
   s.add_runtime_dependency 'rack', '>= 1.3.0'
   s.add_runtime_dependency 'rack-mount'
   s.add_runtime_dependency 'rack-accept'
@@ -33,11 +31,12 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'cookiejar'
   s.add_development_dependency 'rack-contrib'
-  s.add_development_dependency 'mime-types'
+  s.add_development_dependency 'mime-types', '< 3.0'
   s.add_development_dependency 'appraisal'
+  s.add_development_dependency 'benchmark-ips'
+  s.add_development_dependency 'rubocop', '0.35.1'
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.files         = Dir['**/*'].keep_if { |file| File.file?(file) }
+  s.test_files    = Dir['spec/**/*']
   s.require_paths = ['lib']
 end

data/lib/grape/api.rb

@@ -1,14 +1,17 @@
 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.
+  # 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 << self
       attr_reader :instance
+
+      # A class-level lock to ensure the API is not compiled by multiple
+      # threads simultaneously within the same process.
       LOCK = Mutex.new
 
+      # Clears all defined routes, endpoints, etc., on this API.
       def reset!
         @route_set = Rack::Mount::RouteSet.new
         @endpoints = []
@@ -16,32 +19,42 @@ module Grape
         reset_validations!
       end
 
+      # Parses the API's definition and compiles it into an instance of
+      # Grape::API.
       def compile
         @instance ||= new
       end
 
+      # Wipe the compiled API so we can recompile after changes were made.
       def change!
         @instance = nil
       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)
       end
 
+      # A non-synchronized version of ::call.
       def call!(env)
         instance.call(env)
       end
 
       # Create a scope without affecting the URL.
       #
-      # @param name [Symbol] Purely placebo, just allows to name the scope to make the code more readable.
+      # @param _name [Symbol] Purely placebo, just allows to name the scope to
+      # make the code more readable.
       def scope(_name = nil, &block)
         within_namespace do
           nest(block)
         end
       end
 
+      # (see #cascade?)
       def cascade(value = nil)
         if value.nil?
           inheritable_setting.namespace_inheritable.keys.include?(:cascade) ? !!namespace_inheritable(:cascade) : true
@@ -84,6 +97,8 @@ module Grape
       end
     end
 
+    # Builds the routes from the defined endpoints, effectively compiling
+    # this API into a usable form.
     def initialize
       @route_set = Rack::Mount::RouteSet.new
       add_head_not_allowed_methods_and_options_methods
@@ -94,6 +109,7 @@ module Grape
       @route_set.freeze
     end
 
+    # Handle a request. See Rack documentation for what `env` is.
     def call(env)
       result = @route_set.call(env)
       result[1].delete(Grape::Http::Headers::X_CASCADE) unless cascade?
@@ -168,6 +184,8 @@ module Grape
       end
     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)
@@ -181,6 +199,8 @@ module Grape
       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)
 

data/lib/grape/dsl/callbacks.rb

@@ -2,24 +2,44 @@ require 'active_support/concern'
 
 module Grape
   module DSL
+    # Blocks can be executed before or after every API call, using `before`, `after`,
+    # `before_validation` and `after_validation`.
+    #
+    # Before and after callbacks execute in the following order:
+    #
+    # 1. `before`
+    # 2. `before_validation`
+    # 3. _validations_
+    # 4. `after_validation`
+    # 5. _the API call_
+    # 6. `after`
+    #
+    # Steps 4, 5 and 6 only happen if validation succeeds.
     module Callbacks
       extend ActiveSupport::Concern
 
       include Grape::DSL::Configuration
 
       module ClassMethods
+        # Execute the given block before validation, coercion, or any endpoint
+        # code is executed.
         def before(&block)
           namespace_stackable(:befores, block)
         end
 
+        # Execute the given block after `before`, but prior to validation or
+        # coercion.
         def before_validation(&block)
           namespace_stackable(:before_validations, block)
         end
 
+        # Execute the given block after validations and coercions, but before
+        # any endpoint code.
         def after_validation(&block)
           namespace_stackable(:after_validations, block)
         end
 
+        # Execute the given block after the endpoint code has run.
         def after(&block)
           namespace_stackable(:afters, block)
         end