grape 0.12.0 → 0.13.0

data/lib/grape/dsl/configuration.rb

@@ -10,6 +10,9 @@ module Grape
 
         include Grape::DSL::Settings
 
+        # Set or retrive the configured logger. If none was configured, this
+        # method will create a new one, logging to stdout.
+        # @param logger [Object] the new logger to use
         def logger(logger = nil)
           if logger
             global_setting(:logger, logger)
@@ -19,6 +22,39 @@ module Grape
         end
 
         # Add a description to the next namespace or function.
+        # @param description [String] descriptive string for this endpoint
+        #   or namespace
+        # @param options [Hash] other properties you can set to describe the
+        #   endpoint or namespace. Optional.
+        # @option options :detail [String] additional detail about this endpoint
+        # @option options :params [Hash] param types and info. normally, you set
+        #   these via the `params` dsl method.
+        # @option options :entity [Grape::Entity] the entity returned upon a
+        #   successful call to this action
+        # @option options :http_codes [Array[Array]] possible HTTP codes this
+        #   endpoint may return, with their meanings, in a 2d array
+        # @option options :named [String] a specific name to help find this route
+        # @option options :headers [Hash] HTTP headers this method can accept
+        # @yield a block yielding an instance context with methods mapping to
+        #   each of the above, except that :entity is also aliased as #success
+        #   and :http_codes is aliased as #failure.
+        #
+        # @example
+        #
+        #     desc 'create a user'
+        #     post '/users' do
+        #       # ...
+        #     end
+        #
+        #     desc 'find a user' do
+        #       detail 'locates the user from the given user ID'
+        #       failure [ [404, 'Couldn\'t find the given user' ] ]
+        #       success User::Entity
+        #     end
+        #     get '/user/:id' do
+        #       # ...
+        #     end
+        #
         def desc(description, options = {}, &config_block)
           if block_given?
             config_class = Grape::DSL::Configuration.desc_container
@@ -36,15 +72,33 @@ module Grape
           namespace_setting :description, options
           route_setting :description, options
         end
+
+        def description_field(field, value = nil)
+          if value
+            description = route_setting(:description)
+            description ||= route_setting(:description, {})
+            description[field] = value
+          else
+            description = route_setting(:description)
+            description[field] if description
+          end
+        end
+
+        def unset_description_field(field)
+          description = route_setting(:description)
+          description.delete(field) if description
+        end
       end
 
       module_function
 
+      # Merge multiple layers of settings into one hash.
       def stacked_hash_to_hash(settings)
         return nil if settings.nil? || settings.blank?
         settings.each_with_object(ActiveSupport::OrderedHash.new) { |value, result| result.deep_merge!(value) }
       end
 
+      # Returns an object which configures itself via an instance-context DSL.
       def desc_container
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(

data/lib/grape/dsl/inside_route.rb

@@ -177,12 +177,34 @@ module Grape
       #   GET /file # => "contents of file"
       def file(value = nil)
         if value
-          @file = value
+          @file = Grape::Util::FileResponse.new(value)
         else
           @file
         end
       end
 
+      # Allows you to define the response as a streamable object.
+      #
+      # If Content-Length and Transfer-Encoding are blank (among other conditions),
+      # Rack assumes this response can be streamed in chunks.
+      #
+      # @example
+      #   get '/stream' do
+      #     stream FileStreamer.new(...)
+      #   end
+      #
+      #   GET /stream # => "chunked contents of file"
+      #
+      # See:
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/chunked.rb
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/etag.rb
+      def stream(value = nil)
+        header 'Content-Length', nil
+        header 'Transfer-Encoding', nil
+        header 'Cache-Control', 'no-cache' # Skips ETag generation (reading the response up front)
+        file(value)
+      end
+
       # Allows you to make use of Grape Entities by setting
       # the response body to the serializable hash of the
       # entity provided in the `:with` option. This has the
@@ -238,6 +260,14 @@ module Grape
         env['rack.routing_args'][:route_info]
       end
 
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @param options [Hash]
+      # @option options :with [Class] the explicit entity class to use
+      # @return [Class] the located Entity class, or nil if none is found
       def entity_class_for_obj(object, options)
         entity_class = options.delete(:with)
 
@@ -259,6 +289,8 @@ module Grape
         entity_class
       end
 
+      # @return the representation of the given object as done through
+      #   the given entity_class.
       def entity_representation_for(entity_class, object, options)
         embeds = { env: env }
         embeds[:version] = env['api.version'] if env['api.version']

data/lib/grape/dsl/parameters.rb

@@ -2,6 +2,9 @@ require 'active_support/concern'
 
 module Grape
   module DSL
+    # Defines DSL methods, meant to be applied to a ParamsScope, which define
+    # and describe the parameters accepted by an endpoint, or all endpoints
+    # within a namespace.
     module Parameters
       extend ActiveSupport::Concern
 
@@ -39,6 +42,47 @@ module Grape
       alias_method :use_scope, :use
       alias_method :includes, :use
 
+      # Require one or more parameters for the current endpoint.
+      #
+      # @param attrs list of parameter names, or, if :using is
+      #   passed as an option, which keys to include (:all or :none) from
+      #   the :using hash. The last key can be a hash, which specifies
+      #   options for the parameters
+      # @option attrs :type [Class] the type to coerce this parameter to before
+      #   passing it to the endpoint. See Grape::ParameterTypes for supported
+      #   types, or use a class that defines `::parse` as a custom type
+      # @option attrs :desc [String] description to document this parameter
+      # @option attrs :default [Object] default value, if parameter is optional
+      # @option attrs :values [Array] permissable values for this field. If any
+      #   other value is given, it will be handled as a validation error
+      # @option attrs :using [Hash[Symbol => Hash]] a hash defining keys and
+      #   options, like that returned by Grape::Entity#documentation. The value
+      #   of each key is an options hash accepting the same parameters
+      # @option attrs :except [Array[Symbol]] a list of keys to exclude from
+      #   the :using Hash. The meaning of this depends on if :all or :none was
+      #   passed; :all + :except will make the :except fields optional, whereas
+      #   :none + :except will make the :except fields required
+      #
+      # @example
+      #
+      #     params do
+      #       # Basic usage: require a parameter of a certain type
+      #       requires :user_id, type: Integer
+      #
+      #       # You don't need to specify type; String is default
+      #       requires :foo
+      #
+      #       # Multiple params can be specified at once if they share
+      #       # the same options.
+      #       requires :x, :y, :z, type: Date
+      #
+      #       # Nested parameters can be handled as hashes. You must
+      #       # pass in a block, within which you can use any of the
+      #       # parameters DSL methods.
+      #       requires :user, type: Hash do
+      #         requires :name, type: String
+      #       end
+      #     end
       def requires(*attrs, &block)
         orig_attrs = attrs.clone
 
@@ -55,6 +99,10 @@ module Grape
         end
       end
 
+      # Allow, but don't require, one or more parameters for the current
+      #   endpoint.
+      # @param (see #requires)
+      # @option (see #requires)
       def optional(*attrs, &block)
         orig_attrs = attrs.clone
 
@@ -77,24 +125,56 @@ module Grape
         end
       end
 
+      # Disallow the given parameters to be present in the same request.
+      # @param attrs [*Symbol] parameters to validate
       def mutually_exclusive(*attrs)
         validates(attrs, mutual_exclusion: true)
       end
 
+      # Require exactly one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def exactly_one_of(*attrs)
         validates(attrs, exactly_one_of: true)
       end
 
+      # Require at least one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def at_least_one_of(*attrs)
         validates(attrs, at_least_one_of: true)
       end
 
+      # Require that either all given params are present, or none are.
+      # @param (see #mutually_exclusive)
       def all_or_none_of(*attrs)
         validates(attrs, all_or_none_of: true)
       end
 
+      # Define a block of validations which should be applied if and only if
+      # the given parameter is present. The parameters are not nested.
+      # @param attr [Symbol] the parameter which, if present, triggers the
+      #   validations
+      # @throws Grape::Exceptions::UnknownParameter if `attr` has not been
+      #   defined in this scope yet
+      # @yield a parameter definition DSL
+      def given(attr, &block)
+        fail Grape::Exceptions::UnknownParameter.new(attr) unless declared_param?(attr)
+        new_lateral_scope(dependent_on: attr, &block)
+      end
+
+      # Test for whether a certain parameter has been defined in this params
+      # block yet.
+      # @returns [Boolean] whether the parameter has been defined
+      def declared_param?(param)
+        # @declared_params also includes hashes of options and such, but those
+        # won't be flattened out.
+        @declared_params.flatten.include?(param)
+      end
+
       alias_method :group, :requires
 
+      # @param params [Hash] initial hash of parameters
+      # @return hash of parameters relevant for the current scope
+      # @api private
       def params(params)
         params = @parent.params(params) if @parent
         if @element

data/lib/grape/dsl/routing.rb

@@ -135,6 +135,18 @@ module Grape
           end
         end
 
+        # Declare a "namespace", which prefixes all subordinate routes with its
+        # name. Any endpoints within a namespace, or group, resource, segment,
+        # etc., will share their parent context as well as any configuration
+        # done in the namespace context.
+        #
+        # @example
+        #
+        #     namespace :foo do
+        #       get 'bar' do
+        #         # defines the endpoint: GET /foo/bar
+        #       end
+        #     end
         def namespace(space = nil, options = {}, &block)
           if space || block_given?
             within_namespace do
@@ -162,6 +174,7 @@ module Grape
           @routes ||= prepare_routes
         end
 
+        # Remove all defined routes.
         def reset_routes!
           @routes = nil
         end
@@ -177,6 +190,7 @@ module Grape
           namespace(":#{param}", options, &block)
         end
 
+        # @return array of defined versions
         def versions
           @versions ||= []
         end

data/lib/grape/dsl/settings.rb

@@ -2,24 +2,37 @@ require 'active_support/concern'
 
 module Grape
   module DSL
+    # Keeps track of settings (impemented as key-value pairs, grouped by
+    # types), in two contexts: top-level settings which apply globally no
+    # matter where they're defined, and inheritable settings which apply only
+    # in the current scope and scopes nested under it.
     module Settings
       extend ActiveSupport::Concern
 
       attr_accessor :inheritable_setting, :top_level_setting
 
+      # Fetch our top-level settings, which apply to all endpoints in the API.
       def top_level_setting
         @top_level_setting ||= Grape::Util::InheritableSetting.new
       end
 
+      # Fetch our current inheritable settings, which are inherited by
+      # nested scopes but not shared across siblings.
       def inheritable_setting
         @inheritable_setting ||= Grape::Util::InheritableSetting.new.tap { |new_settings| new_settings.inherit_from top_level_setting }
       end
 
+      # @param type [Symbol]
+      # @param key [Symbol]
       def unset(type, key)
         setting = inheritable_setting.send(type)
         setting.delete key
       end
 
+      # @param type [Symbol]
+      # @param key [Symbol]
+      # @param value [Object] will be stored if the value is currently empty
+      # @return either the old value, if it wasn't nil, or the given value
       def get_or_set(type, key, value)
         setting = inheritable_setting.send(type)
         if value.nil?
@@ -29,72 +42,94 @@ module Grape
         end
       end
 
+      # @param key [Symbol]
+      # @param value [Object]
+      # @return (see #get_or_set)
       def global_setting(key, value = nil)
         get_or_set :global, key, value
       end
 
+      # @param key [Symbol]
       def unset_global_setting(key)
         unset :global, key
       end
 
+      # (see #global_setting)
       def route_setting(key, value = nil)
         get_or_set :route, key, value
       end
 
+      # (see #unset_global_setting)
       def unset_route_setting(key)
         unset :route, key
       end
 
+      # (see #global_setting)
       def namespace_setting(key, value = nil)
         get_or_set :namespace, key, value
       end
 
+      # (see #unset_global_setting)
       def unset_namespace_setting(key)
         unset :namespace_setting, key
       end
 
+      # (see #global_setting)
       def namespace_inheritable(key, value = nil)
         get_or_set :namespace_inheritable, key, value
       end
 
+      # (see #unset_global_setting)
       def unset_namespace_inheritable(key)
         unset :namespace_inheritable, key
       end
 
+      # @param key [Symbol]
       def namespace_inheritable_to_nil(key)
         inheritable_setting.namespace_inheritable[key] = nil
       end
 
+      # (see #global_setting)
       def namespace_stackable(key, value = nil)
         get_or_set :namespace_stackable, key, value
       end
 
+      # (see #unset_global_setting)
       def unset_namespace_stackable(key)
         unset :namespace_stackable, key
       end
 
+      # (see #global_setting)
       def api_class_setting(key, value = nil)
         get_or_set :api_class, key, value
       end
 
+      # (see #unset_global_setting)
       def unset_api_class_setting(key)
         unset :api_class_setting, key
       end
 
+      # Fork our inheritable settings to a new instance, copied from our
+      # parent's, but separate so we won't modify it. Every call to this
+      # method should have an answering call to #namespace_end.
       def namespace_start
         @inheritable_setting = Grape::Util::InheritableSetting.new.tap { |new_settings| new_settings.inherit_from inheritable_setting }
       end
 
+      # Set the inheritable settings pointer back up by one level.
       def namespace_end
         route_end
         @inheritable_setting = inheritable_setting.parent
       end
 
+      # Stop defining settings for the current route and clear them for the
+      # next, within a namespace.
       def route_end
         inheritable_setting.route_end
-        reset_validations!
       end
 
+      # Execute the block within a context where our inheritable settings are forked
+      # to a new copy (see #namespace_start).
       def within_namespace(&_block)
         namespace_start
 

data/lib/grape/dsl/validations.rb

@@ -8,22 +8,24 @@ module Grape
       include Grape::DSL::Configuration
 
       module ClassMethods
+        # Clears all defined parameters and validations.
         def reset_validations!
           unset_namespace_stackable :declared_params
           unset_namespace_stackable :validations
           unset_namespace_stackable :params
+          unset_description_field :params
         end
 
+        # Opens a root-level ParamsScope, defining parameter coercions and
+        # validations for the endpoint.
+        # @yield instance context of the new scope
         def params(&block)
           Grape::Validations::ParamsScope.new(api: self, type: Hash, &block)
         end
 
         def document_attribute(names, opts)
-          route_setting(:description, {}) unless route_setting(:description)
-
-          route_setting(:description)[:params] ||= {}
-
-          setting = route_setting(:description)[:params]
+          setting = description_field(:params)
+          setting ||= description_field(:params, {})
           Array(names).each do |name|
             setting[name[:full_name].to_s] ||= {}
             setting[name[:full_name].to_s].merge!(opts)

data/lib/grape/endpoint.rb

@@ -41,10 +41,16 @@ module Grape
         if instance_methods.include?(method_name.to_sym) || instance_methods.include?(method_name.to_s)
           fail NameError.new("method #{method_name.inspect} already exists and cannot be used as an unbound method name")
         end
+
         define_method(method_name, &block)
         method = instance_method(method_name)
         remove_method(method_name)
-        proc { |endpoint_instance| method.bind(endpoint_instance).call }
+
+        proc do |endpoint_instance|
+          ActiveSupport::Notifications.instrument('endpoint_render.grape', endpoint: endpoint_instance) do
+            method.bind(endpoint_instance).call
+          end
+        end
       end
     end
 
@@ -210,47 +216,49 @@ module Grape
     protected
 
     def run(env)
-      @env = env
-      @header = {}
+      ActiveSupport::Notifications.instrument('endpoint_run.grape', endpoint: self, env: env) do
+        @env = env
+        @header = {}
 
-      @request = Grape::Request.new(env)
-      @params = @request.params
-      @headers = @request.headers
+        @request = Grape::Request.new(env)
+        @params = @request.params
+        @headers = @request.headers
 
-      cookies.read(@request)
+        cookies.read(@request)
 
-      self.class.before_each.call(self) if self.class.before_each
+        self.class.before_each.call(self) if self.class.before_each
 
-      run_filters befores
+        run_filters befores, :before
 
-      run_filters before_validations
+        run_filters before_validations, :before_validation
 
-      # Retrieve validations from this namespace and all parent namespaces.
-      validation_errors = []
+        # Retrieve validations from this namespace and all parent namespaces.
+        validation_errors = []
 
-      # require 'pry-byebug'; binding.pry
+        # require 'pry-byebug'; binding.pry
 
-      route_setting(:saved_validations).each do |validator|
-        begin
-          validator.validate!(params)
-        rescue Grape::Exceptions::Validation => e
-          validation_errors << e
+        route_setting(:saved_validations).each do |validator|
+          begin
+            validator.validate!(params)
+          rescue Grape::Exceptions::Validation => e
+            validation_errors << e
+          end
         end
-      end
 
-      if validation_errors.any?
-        fail Grape::Exceptions::ValidationErrors, errors: validation_errors
-      end
+        if validation_errors.any?
+          fail Grape::Exceptions::ValidationErrors, errors: validation_errors, headers: header
+        end
 
-      run_filters after_validations
+        run_filters after_validations, :after_validation
 
-      response_object = @block ? @block.call(self) : nil
-      run_filters afters
-      cookies.write(header)
+        response_object = @block ? @block.call(self) : nil
+        run_filters afters, :after
+        cookies.write(header)
 
-      # The Body commonly is an Array of Strings, the application instance itself, or a File-like object.
-      response_object = file || [body || response_object]
-      [status, header, response_object]
+        # The Body commonly is an Array of Strings, the application instance itself, or a File-like object.
+        response_object = file || [body || response_object]
+        [status, header, response_object]
+      end
     end
 
     def build_middleware
@@ -305,9 +313,11 @@ module Grape
       mod
     end
 
-    def run_filters(filters)
-      (filters || []).each do |filter|
-        instance_eval(&filter)
+    def run_filters(filters, type = :other)
+      ActiveSupport::Notifications.instrument('endpoint_run_filters.grape', endpoint: self, filters: filters, type: type) do
+        (filters || []).each do |filter|
+          instance_eval(&filter)
+        end
       end
     end
 

data/lib/grape/exceptions/unknown_parameter.rb

@@ -0,0 +1,10 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class UnknownParameter < Base
+      def initialize(param)
+        super(message: compose_message('unknown_parameter', param: param))
+      end
+    end
+  end
+end

data/lib/grape/exceptions/validation_errors.rb

@@ -13,7 +13,8 @@ module Grape
           @errors[validation_error.params] ||= []
           @errors[validation_error.params] << validation_error
         end
-        super message: full_messages.join(', '), status: 400
+
+        super message: full_messages.join(', '), status: 400, headers: args[:headers]
       end
 
       def each
@@ -37,12 +38,12 @@ module Grape
         as_json.to_json
       end
 
-      private
-
       def full_messages
         map { |attributes, error| full_message(attributes, error) }.uniq
       end
 
+      private
+
       def full_message(attributes, error)
         I18n.t(
           'grape.errors.format'.to_sym,

data/lib/grape/http/headers.rb

@@ -20,7 +20,6 @@ module Grape
       HTTP_TRANSFER_ENCODING = 'HTTP_TRANSFER_ENCODING'.freeze
       HTTP_ACCEPT            = 'HTTP_ACCEPT'.freeze
 
-      ACCEPT                 = 'accept'.freeze
       FORMAT                 = 'format'.freeze
     end
   end

data/lib/grape/http/request.rb

@@ -1,10 +1,15 @@
 module Grape
   class Request < Rack::Request
+    ROUTING_ARGS = 'rack.routing_args'
+    HTTP_PREFIX  = 'HTTP_'
+    UNDERSCORE   = '_'
+    MINUS        = '-'
+
     def params
       @params ||= begin
         params = Hashie::Mash.new(super)
-        if env['rack.routing_args']
-          args = env['rack.routing_args'].dup
+        if env[ROUTING_ARGS]
+          args = env[ROUTING_ARGS].dup
           # preserve version from query string parameters
           args.delete(:version)
           args.delete(:route_info)
@@ -16,8 +21,11 @@ module Grape
 
     def headers
       @headers ||= env.dup.inject({}) do |h, (k, v)|
-        if k.to_s.start_with? 'HTTP_'
-          k = k[5..-1].tr('_', '-').downcase.gsub(/^.|[-_\s]./) { |x| x.upcase }
+        if k.to_s.start_with? HTTP_PREFIX
+          k = k[5..-1]
+          k.tr!(UNDERSCORE, MINUS)
+          k.downcase!
+          k.gsub!(/^.|[-_\s]./, &:upcase!)
           h[k] = v
         end
         h

data/lib/grape/locale/en.yml

@@ -28,6 +28,7 @@ en:
           resolution: 'available strategy for :using is :path, :header, :param'
         unknown_validator: 'unknown validator: %{validator_type}'
         unknown_options: 'unknown options: %{options}'
+        unknown_parameter: 'unknown parameter: %{param}'
         incompatible_option_values: '%{option1}: %{value1} is incompatible with %{option2}: %{value2}'
         mutual_exclusion: 'are mutually exclusive'
         at_least_one: 'are missing, at least one parameter must be provided'

data/lib/grape/middleware/base.rb

@@ -37,6 +37,7 @@ module Grape
       end
 
       def response
+        return @app_response if @app_response.is_a?(Rack::Response)
         Rack::Response.new(@app_response[2], @app_response[0], @app_response[1])
       end