grape 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3bc83c8aa5374d62068477b48daebd22f10c1761
-  data.tar.gz: a91b6bf2854b1476b9565e3303efa4a67e431b17
+  metadata.gz: 6cfff6fd29d73a9f0c990999725d77521054eaed
+  data.tar.gz: 66ad4e087e432fe5c5d57641db83e5a78730d110
 SHA512:
-  metadata.gz: 555a5eb54fc665f51ae44d4e3103e2c9b4ce92c3fc594c20cbb4001efdbe6515e95200fabe30455085b0a7b3ccaf178dbc1bb2ba75c6bdb5100a75521341614c
-  data.tar.gz: e66803d3c8454744ea814d2d68e0e5fccaab9c544ddfeacf27c64b68aacd36821612875fa263b2d844c307e6dacc48655f98a594c4ecb1f87d595441abf56ee9
+  metadata.gz: 3949ea88f5dd3f57167aaf201789ac4619a334d778cba2b2c8e335a96060d76aa3f218234f5cc2597a2aea23d37bf29baed46505997fe4f7498231734af1b304
+  data.tar.gz: 0c903f1ba5a4d5f1cd4c75c9fd6fb10ef55aefe18543810aa81d8d14f3571133429aee42555972618f6f1608d83dbd66b3cf71df25758634770bc03902ea32a9

data/CHANGELOG.md

@@ -1,12 +1,40 @@
-0.14.0 (12/17/2015)
+0.15.0 (3/8/2016)
+=================
+
+#### Features
+
+* [#1227](https://github.com/ruby-grape/grape/pull/1227): Store `message_key` on `Grape::Exceptions::Validation` - [@stjhimy](https://github.com/sthimy).
+* [#1232](https://github.com/ruby-grape/grape/pull/1232): Helpers are now available inside `rescue_from` - [@namusyaka](https://github.com/namusyaka).
+* [#1237](https://github.com/ruby-grape/grape/pull/1237): Allow multiple parameters in `given`, which behaves as if the scopes were nested in the inputted order - [@ochagata](https://github.com/ochagata).
+* [#1238](https://github.com/ruby-grape/grape/pull/1238): Call `after` of middleware on error - [@namusyaka](https://github.com/namusyaka).
+* [#1243](https://github.com/ruby-grape/grape/pull/1243): Add `header` support for middleware - [@namusyaka](https://github.com/namusyaka).
+* [#1252](https://github.com/ruby-grape/grape/pull/1252): Allow default to be a subset or equal to allowed values without raising IncompatibleOptionValues - [@jeradphelps](https://github.com/jeradphelps).
+* [#1255](https://github.com/ruby-grape/grape/pull/1255): Allow param type definition in `route_param` - [@namusyaka](https://github.com/namusyaka).
+* [#1257](https://github.com/ruby-grape/grape/pull/1257): Allow Proc, Symbol or String in `rescue_from with: ...` - [@namusyaka](https://github.com/namusyaka).
+* [#1280](https://github.com/ruby-grape/grape/pull/1280): Support `Rack::Sendfile` middleware - [@lfidnl](https://github.com/lfidnl).
+* [#1285](https://github.com/ruby-grape/grape/pull/1285): Add a warning for errors appearing in `after` callbacks - [@gregormelhorn](https://github.com/gregormelhorn).
+* [#1295](https://github.com/ruby-grape/grape/pull/1295): Add custom validation messages for parameter exceptions - [@railsmith](https://github.com/railsmith).
+
+#### Fixes
+
+* [#1216](https://github.com/ruby-grape/grape/pull/1142): Fix JSON error response when calling `error!` with non-Strings - [@jrforrest](https://github.com/jrforrest).
+* [#1225](https://github.com/ruby-grape/grape/pull/1225): Fix `given` with nested params not returning correct declared params - [@JanStevens](https://github.com/JanStevens).
+* [#1249](https://github.com/ruby-grape/grape/pull/1249): Don't fail even if invalid type value is passed to default validator - [@namusyaka](https://github.com/namusyaka).
+* [#1266](https://github.com/ruby-grape/grape/pull/1266): Fix `Allow` header including `OPTIONS` when `do_not_route_options!` is active - [@arempe93](https://github.com/arempe93).
+* [#1270](https://github.com/ruby-grape/grape/pull/1270): Fix `param` versioning with a custom parameter - [@wshatch](https://github.com/wshatch).
+* [#1282](https://github.com/ruby-grape/grape/pull/1282): Fix specs circular dependency - [@304](https://github.com/304).
+* [#1283](https://github.com/ruby-grape/grape/pull/1283): Fix 500 error for xml format when method is not allowed - [@304](https://github.com/304).
+* [#1197](https://github.com/ruby-grape/grape/pull/1290): Fix using JSON and Array[JSON] as groups when parameter is optional - [@lukeivers](https://github.com/lukeivers).
+
+0.14.0 (12/07/2015)
 ===================
 
 #### Features
 
 * [#1218](https://github.com/ruby-grape/grape/pull/1218): Provide array index context in errors - [@towanda](https://github.com/towanda).
 * [#1196](https://github.com/ruby-grape/grape/pull/1196): Allow multiple `before_each` blocks - [@huynhquancam](https://github.com/huynhquancam).
-* [#1190](https://github.com/ruby-grape/grape/putt/1190): Bypass formatting for statuses with no entity-body - [@tylerdooling](https://github.com/tylerdooling).
-* [#1188](https://github.com/ruby-grape/grape/putt/1188): Allow parameters with more than one type - [@dslh](https://github.com/dslh).
+* [#1190](https://github.com/ruby-grape/grape/pull/1190): Bypass formatting for statuses with no entity-body - [@tylerdooling](https://github.com/tylerdooling).
+* [#1188](https://github.com/ruby-grape/grape/pull/1188): Allow parameters with more than one type - [@dslh](https://github.com/dslh).
 * [#1179](https://github.com/ruby-grape/grape/pull/1179): Allow all RFC6838 valid characters in header vendor - [@suan](https://github.com/suan).
 * [#1170](https://github.com/ruby-grape/grape/pull/1170): Allow dashes and periods in header vendor - [@suan](https://github.com/suan).
 * [#1167](https://github.com/ruby-grape/grape/pull/1167): Convenience wrapper `type: File` for validating multipart file parameters - [@dslh](https://github.com/dslh).
@@ -23,7 +51,7 @@
 * [#1142](https://github.com/ruby-grape/grape/pull/1142): Makes #declared unavailable to before filters - [@jrforrest](https://github.com/jrforrest).
 * [#1114](https://github.com/ruby-grape/grape/pull/1114): Fix regression which broke identical endpoints with different versions - [@suan](https://github.com/suan).
 * [#1109](https://github.com/ruby-grape/grape/pull/1109): Memoize Virtus attribute and fix memory leak - [@marshall-lee](https://github.com/marshall-lee).
-* [#1101](https://github.com/intridea/grape/pull/1101): Fix: Incorrect media-type `Accept` header now correctly returns 406 with `strict: true` - [@elliotlarson](https://github.com/elliotlarson).
+* [#1101](https://github.com/ruby-grape/grape/pull/1101): Fix: Incorrect media-type `Accept` header now correctly returns 406 with `strict: true` - [@elliotlarson](https://github.com/elliotlarson).
 * [#1108](https://github.com/ruby-grape/grape/pull/1039): Raise a warning when `desc` is called with options hash and block - [@rngtng](https://github.com/rngtng).
 
 0.13.0 (8/10/2015)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grape (0.14.0)
+    grape (0.15.0)
       activesupport
       builder
       hashie (>= 2.1.0)
@@ -15,7 +15,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.5)
+    activesupport (4.2.5.1)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
@@ -25,7 +25,7 @@ GEM
       bundler
       rake
       thor (>= 0.14.0)
-    ast (2.1.0)
+    ast (2.2.0)
     astrolabe (1.3.1)
       parser (~> 2.2)
     axiom-types (0.1.1)
@@ -45,7 +45,7 @@ GEM
     ffi (1.9.10)
     formatador (0.2.5)
     git-version-bump (0.15.1)
-    grape-entity (0.4.8)
+    grape-entity (0.5.0)
       activesupport
       multi_json (>= 1.3.2)
     guard (2.13.0)
@@ -67,24 +67,24 @@ GEM
       rubocop (~> 0.20)
     hashie (3.4.3)
     i18n (0.7.0)
-    ice_nine (0.11.1)
+    ice_nine (0.11.2)
     json (1.8.3)
     listen (3.0.5)
       rb-fsevent (>= 0.9.3)
       rb-inotify (>= 0.9)
-    lumberjack (1.0.9)
+    lumberjack (1.0.10)
     maruku (0.7.2)
     method_source (0.8.2)
     mime-types (2.99)
-    minitest (5.8.3)
+    minitest (5.8.4)
     multi_json (1.11.2)
     multi_xml (0.5.5)
     nenv (0.2.0)
     notiffany (0.0.8)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    parser (2.2.3.0)
-      ast (>= 1.1, < 3.0)
+    parser (2.3.0.6)
+      ast (~> 2.2)
     powerpack (0.1.1)
     pry (0.10.3)
       coderay (~> 1.1.0)
@@ -100,9 +100,9 @@ GEM
       rack (>= 1.0.0)
     rack-test (0.6.3)
       rack (>= 1.0)
-    rainbow (2.0.0)
-    rake (10.4.2)
-    rb-fsevent (0.9.6)
+    rainbow (2.1.0)
+    rake (10.5.0)
+    rb-fsevent (0.9.7)
     rb-inotify (0.9.5)
       ffi (>= 0.5.0)
     rspec (3.4.0)
@@ -114,7 +114,7 @@ GEM
     rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.4.0)
-    rspec-mocks (3.4.0)
+    rspec-mocks (3.4.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.4.0)
     rspec-support (3.4.1)

data/README.md

@@ -41,6 +41,7 @@
   - [Custom Validators](#custom-validators)
   - [Validation Errors](#validation-errors)
   - [I18n](#i18n)
+  - [Custom Validation Messages](#custom-validation-messages)
 - [Headers](#headers)
 - [Routes](#routes)
 - [Helpers](#helpers)
@@ -73,6 +74,7 @@
 - [Before and After](#before-and-after)
 - [Anchoring](#anchoring)
 - [Using Custom Middleware](#using-custom-middleware)
+  - [Grape Middleware](#grape-middleware)
   - [Rails Middleware](#rails-middleware)
   - [Remote IP](#remote-ip)
 - [Writing Tests](#writing-tests)
@@ -99,7 +101,7 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grae [0.14.0](https://github.com/ruby-grape/grape/blob/v0.14.0/README.md).
+You're reading the documentation for the stable release of Grape, 0.15.0.
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
@@ -600,10 +602,10 @@ It also works on nested hashes:
 format :json
 
 params do
-  requires :user, :type => Hash do
+  requires :user, type: Hash do
     requires :first_name, type: String
     optional :last_name, type: String
-    requires :address, :type => Hash do
+    requires :address, type: Hash do
       requires :city, type: String
       optional :region, type: String
     end
@@ -1146,6 +1148,19 @@ namespace :statuses do
 end
 ```
 
+You can also define a route parameter type by passing to `route_param`'s options.
+
+```ruby
+namespace :arithmetic do
+  route_param :n, type: Integer do
+    desc 'Returns in power'
+    get 'power' do
+      params[:n] ** params[:n]
+    end
+  end
+end
+```
+
 ### Custom Validators
 
 ```ruby
@@ -1182,6 +1197,35 @@ params do
 end
 ```
 
+You can also create custom validation that use request to validate the attribute. For example if you want to have parameters that are available to only admins, you can do the following.
+
+```ruby
+class Admin < Grape::Validations::Base
+  def validate(request)
+    # return if the param we are checking was not in request
+    # @attrs is a list containing the attribute we are currently validating
+    # in our sample case this method once will get called with
+    # @attrs being [:admin_field] and once with @attrs being [:admin_false_field]
+    return unless request.params.key? @attrs.first
+    # check if admin flag is set to true
+    return unless @option
+    # check if user is admin or not
+    # as an example get a token from request and check if it's admin or not
+    fail Grape::Exceptions::Validation, params: @attrs, message: 'Can not set admin-only field.' unless request.headers['X-Access-Token'] == 'admin'
+  end
+end
+```
+
+And use it in your endpoint definition as:
+
+```ruby
+params do
+  optional :admin_field, type: String, admin: true
+  optional :non_admin_field, type: String
+  optional :admin_false_field, type: String, admin: false
+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. The validation errors are grouped by parameter name and can be accessed via `Grape::Exceptions::ValidationErrors#errors`.
@@ -1222,6 +1266,119 @@ end
 Grape supports I18n for parameter-related error messages, but will fallback to English if
 translations for the default locale have not been provided. See [en.yml](lib/grape/locale/en.yml) for message keys.
 
+### Custom Validation messages
+
+Grape supports custom validation messages for parameter-related and coerce-related error messages.
+
+#### `presence`, `allow_blank`, `values`, `regexp`
+
+```ruby
+params do
+  requires :name, values: { value: 1..10, message: 'not in range from 1 to 10' }, allow_blank: { value: false, message: 'cannot be blank' }, regexp: { value: /^[a-z]+$/, message: 'format is invalid' }, message: 'is required'
+end
+```
+#### `all_or_none_of`
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  all_or_none_of :beer, :wine, :juice, message: "all params are required or none is required"
+end
+```
+
+#### `mutually_exclusive`
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  mutually_exclusive :beer, :wine, :juice, message: "are mutually exclusive cannot pass both params"
+end
+```
+#### `exactly_one_of`
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  exactly_one_of :beer, :wine, :juice, message: {exactly_one: "are missing, exactly one parameter is required", mutual_exclusion: "are mutually exclusive, exactly one parameter is required"}
+end
+```
+#### `at_least_one_of`
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  at_least_one_of :beer, :wine, :juice, message: "are missing, please specify at least one param"
+end
+```
+#### `Coerce`
+
+```ruby
+params do
+  requires :int, type: {value: Integer, message: "type cast is invalid" }
+end
+```
+#### `With Lambdas`
+
+```ruby
+params do
+  requires :name, values: { value: -> { (1..10).to_a }, message: 'not in range from 1 to 10' }
+end
+```
+#### `Pass symbols for i18n translations`
+
+You can pass a symbol if you want i18n translations for your custom validation messages.
+
+```ruby
+params do
+  requires :name, message: :name_required
+end
+```
+```ruby
+# en.yml
+
+en:
+  grape:
+    errors:
+      format: ! '%{attributes} %{message}'
+      messages:
+        name_required: 'must be present'
+```
+
+#### `Overriding attribute names`
+
+You can also override attribute names.
+
+```ruby
+# en.yml
+
+en:
+  grape:
+    errors:
+      format: ! '%{attributes} %{message}'
+      messages:
+        name_required: 'must be present'
+      attributes:
+        name: 'Oops! Name'
+```
+Will produce 'Oops! Name must be present'
+
+#### `With Default`
+
+You cannot set a custom message option for Default as it requires interpolation `%{option1}: %{value1} is incompatible with %{option2}: %{value2}`. You can change the default error message for Default by changing the `incompatible_option_values` message key inside [en.yml](lib/grape/locale/en.yml)
+
+```ruby
+params do
+  requires :name, values: { value: -> { (1..10).to_a }, message: 'not in range from 1 to 10' }, default: 5
+end
+```
 ## Headers
 
 Request headers are available through the `headers` helper or from `env` in their original form.
@@ -1542,6 +1699,12 @@ You can abort the execution of an API method by raising errors with `error!`.
 error! 'Access Denied', 401
 ```
 
+Anything that responds to `#to_s` can be given as a first argument to `error!`.
+
+```ruby
+error! :not_found, 404
+```
+
 You can also return JSON formatted objects by raising error! and passing a hash
 instead of a message.
 
@@ -1562,7 +1725,7 @@ end
 
 The following example specifies the entity to use in the `http_codes` definition.
 
-```
+```ruby
 desc 'My Route' do
  failure [[408, 'Unauthorized', API::Error]]
 end
@@ -1731,8 +1894,41 @@ rescue_from RuntimeError, rescue_subclasses: false do |e|
 end
 ```
 
+Helpers are also available inside `rescue_from`.
+
+```ruby
+class Twitter::API < Grape::API
+  format :json
+  helpers do
+    def server_error!
+      error!({ error: 'Server error.' }, 500, { 'Content-Type' => 'text/error' })
+    end
+  end
+
+  rescue_from :all do |e|
+    server_error!
+  end
+end
+```
+
 The `rescue_from` block must return a `Rack::Response` object, call `error!` or re-raise an exception.
 
+The `with` keyword is available as `rescue_from` options, it can be passed method name or Proc object.
+
+```ruby
+class Twitter::API < Grape::API
+  format :json
+  helpers do
+    def server_error!
+      error!({ error: 'Server error.' }, 500, { 'Content-Type' => 'text/error' })
+    end
+  end
+
+  rescue_from :all,          with: :server_error!
+  rescue_from ArgumentError, with: -> { Rack::Response.new('rescued with a method', 400) }
+end
+```
+
 #### Unrescuable Exceptions
 
 `Grape::Exceptions::InvalidVersionHeader`, which is raised when the version in the request header doesn't match the currently evaluated version for the endpoint, will _never_ be rescued from a `rescue_from` block (even a `rescue_from :all`) This is because Grape relies on Rack to catch that error and try the next versioned-route for cases where there exist identical Grape endpoints with different versions.
@@ -1801,7 +1997,7 @@ class API < Grape::API
 end
 ```
 
-For similar to Rails request logging try the [grape_logging](https://github.com/aserafin/grape_logging) gem.
+For similar to Rails request logging try the [grape_logging](https://github.com/aserafin/grape_logging) or [grape-middleware-logger](https://github.com/ridiculous/grape-middleware-logger) gems.
 
 ## API Formats
 
@@ -1885,7 +2081,7 @@ class Twitter::API < Grape::API
     filename = params[:file][:filename]
     content_type MIME::Types.type_for(filename)[0].to_s
     env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
-    header 'Content-Disposition', "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+    header 'Content-Disposition', "attachment; filename*=UTF-8''#{CGI.escape(filename)}"
     params[:file][:tempfile].read
   end
 end
@@ -2274,6 +2470,30 @@ class API < Grape::API
 end
 ```
 
+If you want to take advantage of `Rack::Sendfile`, which intercepts responses whose body is
+being served from a file and replaces it with a server specific X-Sendfile header, specify `to_path`
+method in your file streamer class which returns path of served file:
+
+```ruby
+class FileStreamer
+  # ...
+
+  def to_path
+    @file_path
+  end
+
+  # ...
+end
+```
+
+Note: don't forget turn on `Rack::Sendfile` middleware in your API:
+
+```ruby
+class API < Grape::API
+  use Rack::Sendfile
+end
+```
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -2399,7 +2619,9 @@ Before and after callbacks execute in the following order:
 
 Steps 4, 5 and 6 only happen if validation succeeds.
 
-E.g. using `before`:
+#### Examples
+
+Using a simple `before` block to set a header
 
 ```ruby
 before do
@@ -2407,7 +2629,9 @@ before do
 end
 ```
 
-The block applies to every API call within and below the current namespace:
+**Namespaces**
+
+Callbacks apply to each API call within and below the current namespace:
 
 ```ruby
 class MyAPI < Grape::API
@@ -2441,8 +2665,7 @@ GET /foo        # 'root - foo - blah'
 GET /foo/bar    # 'root - foo - bar - blah'
 ```
 
-Params on a `namespace` (or whatever alias you are using) also work when using
-`before_validation` or `after_validation`:
+Params on a `namespace` (or whichever alias you are using) will also be available when using `before_validation` or `after_validation`:
 
 ```ruby
 class MyAPI < Grape::API
@@ -2469,6 +2692,8 @@ GET /123        # 'Fixnum'
 GET /foo        # 400 error - 'blah is invalid'
 ```
 
+**Versioning**
+
 When a callback is defined within a version block, it's only called for the routes defined in that block.
 
 ```ruby
@@ -2502,6 +2727,33 @@ GET /foo/v1       # 'v1-hello'
 GET /foo/v2       # 'v2-hello'
 ```
 
+**Altering Responses**
+
+Using `present` in any callback allows you to add data to a response:
+
+```ruby
+class MyAPI < Grape::API
+  format :json
+
+  after_validation do
+    present :name, params[:name] if params[:name]
+  end
+
+  get '/greeting' do
+    present :greeting, 'Hello!'
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /greeting              # {"greeting":"Hello!"}
+GET /greeting?name=Alan    # {"name":"Alan","greeting":"Hello!"}
+```
+
+Instead of altering a response, you can also terminate and rewrite it from any callback using `error!`, including `after`. This will cause all subsequent steps in the process to not be called. **This includes the actual api call and any callbacks**
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL
@@ -2533,6 +2785,32 @@ part.
 
 ## Using Custom Middleware
 
+### Grape Middleware
+
+You can make a custom middleware by using `Grape::Middleware::Base`.
+It's inherited from some grape official middlewares in fact.
+
+For example, you can write a middleware to log application exception.
+
+```ruby
+class LoggingError < Grape::Middleware::Base
+  def after
+    return unless @app_response && @app_response[0] == 500
+    env['rack.logger'].error("Raised error on #{env['PATH_INFO']}")
+  end
+end
+```
+
+Your middleware can overwrite application response as follows, except error case.
+
+```ruby
+class Overwriter < Grape::Middleware::Base
+  def after
+    [200, { 'Content-Type' => 'text/plain' }, ['Overwrited.']]
+  end
+end
+```
+
 ### Rails Middleware
 
 Note that when you're using Grape mounted on Rails you don't have to use Rails middleware because it's already included into your middleware stack.
@@ -2683,7 +2961,7 @@ end
 ```
 
 In Rails, HTTP request tests would go into the `spec/requests` group. You may want your API code to go into
-`app/api` - you can match that layout under `spec` by adding the following in `spec/spec_helper.rb`.
+`app/api` - you can match that layout under `spec` by adding the following in `spec/rails_helper.rb`.
 
 ```ruby
 RSpec.configure do |config|
@@ -2734,7 +3012,7 @@ describe 'an endpoint that needs helpers stubbed' do
     Grape::Endpoint.before_each nil
   end
 
-  it 'should properly stub the helper' do
+  it 'stubs the helper' do
     # ...
   end
 end