grape 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 16ab2241d8805f0449737830d3fb60b5ecf6a1e3
-  data.tar.gz: b2d2d3cce8167bac238d0d8ac770edac583b0a81
+  metadata.gz: 065f62bd14d8e5f24acc6b085a2fd2f7b5cc835a
+  data.tar.gz: 1d95db90f66a6ddcae57416a557ac58977bae3b2
 SHA512:
-  metadata.gz: ead66bb7118fdb6c173dcb4e9459a6385cd1ea984738e60c23754ff1c508d8562ff8d0a161ac7bebd14ec9afc22fd73170b7f15324facfc1ce79e6688d0a2d5b
-  data.tar.gz: 10be3eceb5dcd72fcf5952d4d8bac3fa0eb9eb1a3eb5f08fa14486a2e24dcf21b578886dc314f09b6227d12214fa8ba9326f488405e2082acf1397e397d24d88
+  metadata.gz: 51324bbb02265b2ba09dae20e06039c1cdba09e4fd6f40979328be0bc32bd4fb03628ef90862c41016d14002b8b280906b945532d96b295ab8624dc567a57836
+  data.tar.gz: 93b0e47cbd02e8faad346d2e43b7f7d3bf56f05497331e87c6969dd17c65e8df651b69777e32f8aa9d68f6b17ae113e0094f6e04bf02fe25962959d71d7c7be5

data/.rubocop.yml

@@ -1,7 +1,7 @@
 AllCops:
   Exclude:
-    - vendor/**
-    - bin/**
+    - vendor/**/*
+    - bin/**/*
 
 LineLength:
   Enabled: false
@@ -68,3 +68,5 @@ DoubleNegation:
 
 PredicateName:
   Enabled: false
+
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,80 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2014-08-12 13:16:39 +0200 using RuboCop version 0.24.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 28
+# Cop supports --auto-correct.
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+# Offense count: 30
+# Cop supports --auto-correct.
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+# Offense count: 5
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/ClassCheck:
+  Enabled: false
+
+# Offense count: 6
+Style/EachWithObject:
+  Enabled: false
+
+# Offense count: 11
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/HashSyntax:
+  Enabled: false
+
+# Offense count: 14
+# Cop supports --auto-correct.
+Style/IndentArray:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/IndentHash:
+  Enabled: true
+
+# Offense count: 3
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/Next:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: PreferredDelimiters.
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/SpaceBeforeBlockBraces:
+  Enabled: false
+
+# Offense count: 12
+# Cop supports --auto-correct.
+Style/SpaceBeforeSemicolon:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/SpecialGlobalVars:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Style/UnneededPercentQ:
+  Enabled: false

data/.travis.yml

@@ -3,14 +3,14 @@ language: ruby
 cache: bundler
 
 rvm:
-  - ruby-head
   - 2.1.2
   - 2.1.0
   - 2.0.0
   - 1.9.3
+  - rbx-2.2.10
   - jruby-19mode
+  - ruby-head
   - jruby-head
-  - rbx-2
 
 matrix:
   allow_failures:

data/CHANGELOG.md

@@ -1,11 +1,30 @@
+0.9.0 (8/27/2014)
+=================
+
+#### Features
+
+* [#691](https://github.com/intridea/grape/issues/691): Added `at_least_one_of` parameter validator - [@dblock](https://github.com/dblock).
+* [#698](https://github.com/intridea/grape/pull/698): `error!` sets `status` for `Endpoint` too - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#703](https://github.com/intridea/grape/pull/703): Added support for Auth-Middleware extension - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#703](https://github.com/intridea/grape/pull/703): Removed `Grape::Middleware::Auth::Basic` - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#703](https://github.com/intridea/grape/pull/703): Removed `Grape::Middleware::Auth::Digest` - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#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 with a `Grape::Entity` class - [@dspaeth-faber](https://github.com/dspaeth-faber).
+
+#### Fixes
+
+* [#687](https://github.com/intridea/grape/pull/687): Fix: `mutually_exclusive` and `exactly_one_of` validation error messages now label parameters as strings, consistently with `requires` and `optional` - [@dblock](https://github.com/dblock).
+
 0.8.0 (7/10/2014)
 =================
 
 #### Features
 
 * [#639](https://github.com/intridea/grape/pull/639): Added support for blocks with reusable params - [@mibon](https://github.com/mibon).
-* [#637](https://github.com/intridea/grape/pull/637): Added 'exactly_one_of' validation - [@Morred](https://github.com/Morred).
-* [#626](https://github.com/intridea/grape/pull/626): Mutually exclusive params - [@oliverbarnes](https://github.com/oliverbarnes).
+* [#637](https://github.com/intridea/grape/pull/637): Added support for `exactly_one_of` parameter validation - [@Morred](https://github.com/Morred).
+* [#626](https://github.com/intridea/grape/pull/626): Added support for `mutually_exclusive` parameters - [@oliverbarnes](https://github.com/oliverbarnes).
 * [#617](https://github.com/intridea/grape/pull/617): Running tests on Ruby 2.1.1, Rubinius 2.1 and 2.2, Ruby and JRuby HEAD - [@dblock](https://github.com/dblock).
 * [#397](https://github.com/intridea/grape/pull/397): Adds `Grape::Endpoint.before_each` to allow easy helper stubbing - [@mbleigh](https://github.com/mbleigh).
 * [#673](https://github.com/intridea/grape/pull/673): Avoid requiring non-existent fields when using Grape::Entity documentation - [@qqshfox](https://github.com/qqshfox).

data/Gemfile

@@ -3,15 +3,10 @@ source 'http://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'rspec', '~> 2.14.1'
-  gem 'rack-test', '~> 0.6.2', require: 'rack/test'
-  gem 'cookiejar'
-  gem 'rack-contrib'
-  gem 'rubocop', '~> 0.20.1'
+  gem 'rubocop', '~> 0.24.1'
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
-  gem 'mime-types'
 end
 
 platforms :rbx do

data/Guardfile

@@ -1,13 +1,9 @@
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
-
-guard :rspec do
+guard :rspec, all_on_start: true, cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }
 end
 
-
 guard :rubocop do
   watch(%r{.+\.rb$})
   watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }

data/README.md

@@ -31,6 +31,7 @@
 - [Helpers](#helpers)
 - [Parameter Documentation](#parameter-documentation)
 - [Cookies](#cookies)
+- [HTTP Status Code](#http-status-code)
 - [Redirecting](#redirecting)
 - [Allowed Methods](#allowed-methods)
 - [Raising Exceptions](#raising-exceptions)
@@ -76,8 +77,7 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 0.8.0.
-Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
+You're reading the documentation for Grape [0.9.0](https://github.com/intridea/grape/blob/v0.9.0/README.md).
 
 ## Project Resources
 
@@ -300,6 +300,21 @@ When an invalid `Accept` header is supplied, a `406 Not Acceptable` error is ret
 option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route
 matches.
 
+### HTTP Status Code
+
+By default Grape returns a 200 status code for `GET`-Requests and 201 for `POST`-Requests.
+You can use `status` to query and set the actual HTTP Status Code
+
+```ruby
+post do
+  status 202
+
+  if status == 200
+     # do some thing
+  end
+end
+```
+
 ### Accept-Version Header
 
 ```ruby
@@ -444,12 +459,12 @@ params do
 end
 ```
 
-The :values option can also be supplied with a `Proc` to be evalutated at runtime. For example, given a status
+The `:values` option can also be supplied with a `Proc` to be evalutated at runtime. For example, given a status
 model you may want to restrict by hashtags that you have previously defined in the `HashTag` model.
 
 ```ruby
 params do
-  required :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
+  requires :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
 end
 ```
 
@@ -509,6 +524,17 @@ params do
 end
 ```
 
+Parameters can be defined as 'at_least_one_of', ensuring that at least one parameter gets selected.
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  at_least_one :beer, :wine, :juice
+end
+```
+
 ### Namespace Validation and Coercion
 
 Namespaces allow parameter definitions and apply to every method within the namespace.
@@ -588,21 +614,28 @@ end
 
 ### Validation Errors
 
-Validation and coercion errors are collected and an exception of type `Grape::Exceptions::ValidationErrors` is raised.
-If the exception goes uncaught it will respond with a status of 400 and an error message.
-You can rescue a `Grape::Exceptions::ValidationErrors` and respond with a custom response.
+Validation and coercion errors are collected and an exception of type `Grape::Exceptions::ValidationErrors` is raised. If the exception goes uncaught it will respond with a status of 400 and an error message. The validation errors are grouped by parameter name and can be accessed via `Grape::Exceptions::ValidationErrors#errors`.
+
+
+The default response from a `Grape::Exceptions::ValidationErrors` is a humanly readable string, such as "beer, wine are mutually exclusive", in the following example.
 
 ```ruby
-rescue_from Grape::Exceptions::ValidationErrors do |e|
-    Rack::Response.new({
-      status: e.status,
-      message: e.message,
-      errors: e.errors
-    }.to_json, e.status)
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  exactly_one_of :beer, :wine, :juice
 end
 ```
 
-The validation errors are grouped by parameter name and can be accessed via ``Grape::Exceptions::ValidationErrors#errors``.
+You can rescue a `Grape::Exceptions::ValidationErrors` and respond with a custom response or turn the response into well-formatted JSON for a JSON API that separates individual parameters and the corresponding error messages. The following `rescue_from` example produces `[{"params":["beer","wine"],"messages":["are mutually exclusive"]}]`.
+
+```ruby
+format :json
+subject.rescue_from Grape::Exceptions::ValidationErrors do |e|
+  rack_response e.to_json, 400
+end
+```
 
 ### I18n
 
@@ -909,6 +942,31 @@ instead of a message.
 error!({ error: "unexpected error", detail: "missing widget" }, 500)
 ```
 
+You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/intridea/grape-entity) gem.
+
+```ruby
+module API
+  class Error < Grape::Entity
+    expose :code
+    expose :message
+  end
+end
+```
+
+The following example specifies the entity to use in the `http_codes` definition.
+
+```
+desc 'My Route', http_codes: [[408, 'Unauthorized', API::Error]]
+error!({ message: 'Unauthorized' }, 408)
+```
+
+The following example specifies the presented entity explicitly in the error message.
+
+```ruby
+desc 'My Route', http_codes: [[408, 'Unauthorized']]
+error!({ message: 'Unauthorized', with: API::Error }, 408)
+```
+
 ### Default Error HTTP Status Code
 
 By default Grape returns a 500 status code from `error!`. You can change this with `default_error_status`.
@@ -1412,11 +1470,9 @@ Grape will automatically detect that there is a `Status::Entity` class and use t
 representative entity. This can still be overridden by using the `:with` option or an explicit
 `represents` call.
 
-### Hypermedia
+### Hypermedia and Roar
 
-You can use any Hypermedia representer, including [Roar](https://github.com/apotonick/roar).
-Roar renders JSON and works with the built-in Grape JSON formatter. Add `Roar::Representer::JSON`
-into your models or call `to_json` explicitly in your API implementation.
+You can use [Roar](https://github.com/apotonick/roar) to render HAL or Collection+JSON with the help of [grape-roar](https://github.com/dblock/grape-roar), which defines a custom JSON formatter and enables presenting entities with Grape's `present` keyword.
 
 ### Rabl
 
@@ -1435,7 +1491,9 @@ formatter.
 
 ### Basic and Digest Auth
 
-Grape has built-in Basic and Digest authentication.
+Grape has built-in Basic and Digest authentication (the given `block`
+is executed in the context of the current `Endpoint`).  Authentication
+applies to the current namespace and any children, but not parents.
 
 ```ruby
 http_basic do |username, password|
@@ -1451,6 +1509,33 @@ http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
 end
 ```
 
+### Register custom middleware for authentication
+
+Grape can use custom Middleware for authentication. How to implement these
+Middleware have a look at `Rack::Auth::Basic` or similar implementations.
+
+
+For registering a Middlewar you need the following options:
+
+* `label` - the name for your authenticator to use it later
+* `MiddlewareClass` - the MiddlewareClass to use for authentication
+* `option_lookup_proc` - A Proc with one Argument to lookup the options at
+runtime (return value is an `Array` as Paramter for the Middleware).
+
+Example:
+
+```ruby
+
+Grape::Middleware::Auth::Strategies.add(:my_auth, AuthMiddleware, ->(options) { [options[:realm]] } )
+
+
+auth :my_auth ,{ real: 'Test Api'} do |credentials|
+  # lookup the user's password here
+  { 'user1' => 'password1' }[username]
+end
+
+```
+
 Use [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
 
 ## Describing and Inspecting an API
@@ -1640,15 +1725,15 @@ describe Twitter::API do
     describe "GET /api/v1/statuses" do
       it "returns an empty array of statuses" do
         get "/api/v1/statuses"
-        last_response.status.should == 200
-        JSON.parse(last_response.body).should == []
+        expect(last_response.status).to eq(200)
+        expect(JSON.parse(last_response.body)).to eq []
       end
     end
     describe "GET /api/v1/statuses/:id" do
       it "returns a status by id" do
         status = Status.create!
         get "/api/v1/statuses/#{status.id}"
-        last_response.body.should == status.to_json
+        expect(last_response.body).to eq status.to_json
       end
     end
   end
@@ -1658,21 +1743,19 @@ end
 ### Writing Tests with Rails
 
 ```ruby
-require 'spec_helper'
-
 describe Twitter::API do
   describe "GET /api/v1/statuses" do
     it "returns an empty array of statuses" do
       get "/api/v1/statuses"
-      response.status.should == 200
-      JSON.parse(response.body).should == []
+      expect(response.status).to eq(200)
+      expect(JSON.parse(response.body)).to eq []
     end
   end
   describe "GET /api/v1/statuses/:id" do
     it "returns a status by id" do
       status = Status.create!
       get "/api/v1/statuses/#{status.id}"
-      response.body.should == status.to_json
+      expect(response.body).to eq status.to_json
     end
   end
 end

data/Rakefile

@@ -18,7 +18,7 @@ task :spec
 
 require 'rainbow/ext/string' unless String.respond_to?(:color)
 require 'rubocop/rake_task'
-Rubocop::RakeTask.new(:rubocop)
+RuboCop::RakeTask.new
 
 task default: [:rubocop, :spec]
 

data/UPGRADING.md

@@ -1,6 +1,41 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 0.9.0 
+
+#### Changes in Authentication
+
+The following middleware classes have been removed:
+
+* `Grape::Middleware::Auth::Basic` 
+* `Grape::Middleware::Auth::Digest`
+* `Grape::Middleware::Auth::OAuth2`
+
+When you use theses classes directly like:
+
+```ruby
+ module API
+   class Root < Grape::API
+     class Protected < Grape::API
+       use Grape::Middleware::Auth::OAuth2,
+           token_class: 'AccessToken',
+           parameter: %w(access_token api_key)
+           
+```
+
+you have to replace these classes.
+
+As replacement can be used
+
+* `Grape::Middleware::Auth::Basic`  => [`Rack::Auth::Basic`](https://github.com/rack/rack/blob/master/lib/rack/auth/basic.rb)
+* `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)
+and host these files within your application
+
+See [#703](https://github.com/intridea/Grape/pull/703) for more information.
+
 ### Upgrading to >= 0.7.0
 
 #### Changes in Exception Handling