grape 0.8.0 → 0.9.0

data/lib/grape/dsl/request_response.rb

@@ -0,0 +1,152 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module RequestResponse
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Specify the default format for the API's serializers.
+        # May be `:json` or `:txt` (default).
+        def default_format(new_format = nil)
+          new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
+        end
+
+        # Specify the format for the API's serializers.
+        # May be `:json`, `:xml`, `:txt`, etc.
+        def format(new_format = nil)
+          if new_format
+            set(:format, new_format.to_sym)
+            # define the default error formatters
+            set(:default_error_formatter, Grape::ErrorFormatter::Base.formatter_for(new_format, {}))
+            # define a single mime type
+            mime_type = content_types[new_format.to_sym]
+            raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type
+            settings.imbue(:content_types, new_format.to_sym => mime_type)
+          else
+            settings[:format]
+          end
+        end
+
+        # Specify a custom formatter for a content-type.
+        def formatter(content_type, new_formatter)
+          settings.imbue(:formatters, content_type.to_sym => new_formatter)
+        end
+
+        # Specify a custom parser for a content-type.
+        def parser(content_type, new_parser)
+          settings.imbue(:parsers, content_type.to_sym => new_parser)
+        end
+
+        # Specify a default error formatter.
+        def default_error_formatter(new_formatter_name = nil)
+          if new_formatter_name
+            new_formatter = Grape::ErrorFormatter::Base.formatter_for(new_formatter_name, {})
+            set(:default_error_formatter, new_formatter)
+          else
+            settings[:default_error_formatter]
+          end
+        end
+
+        def error_formatter(format, options)
+          if options.is_a?(Hash) && options.key?(:with)
+            formatter = options[:with]
+          else
+            formatter = options
+          end
+
+          settings.imbue(:error_formatters, format.to_sym => formatter)
+        end
+
+        # Specify additional content-types, e.g.:
+        #   content_type :xls, 'application/vnd.ms-excel'
+        def content_type(key, val)
+          settings.imbue(:content_types, key.to_sym => val)
+        end
+
+        # All available content types.
+        def content_types
+          Grape::ContentTypes.content_types_for(settings[:content_types])
+        end
+
+        # Specify the default status code for errors.
+        def default_error_status(new_status = nil)
+          new_status ? set(:default_error_status, new_status) : settings[:default_error_status]
+        end
+
+        # Allows you to rescue certain exceptions that occur to return
+        # a grape error rather than raising all the way to the
+        # server level.
+        #
+        # @example Rescue from custom exceptions
+        #     class ExampleAPI < Grape::API
+        #       class CustomError < StandardError; end
+        #
+        #       rescue_from CustomError
+        #     end
+        #
+        # @overload rescue_from(*exception_classes, options = {})
+        #   @param [Array] exception_classes A list of classes that you want to rescue, or
+        #     the symbol :all to rescue from all exceptions.
+        #   @param [Block] block Execution block to handle the given exception.
+        #   @param [Hash] options Options for the rescue usage.
+        #   @option options [Boolean] :backtrace Include a backtrace in the rescue response.
+        #   @option options [Boolean] :rescue_subclasses Also rescue subclasses of exception classes
+        #   @param [Proc] handler Execution proc to handle the given exception as an
+        #     alternative to passing a block
+        def rescue_from(*args, &block)
+          if args.last.is_a?(Proc)
+            handler = args.pop
+          elsif block_given?
+            handler = block
+          end
+
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          handler ||= proc { options[:with] } if options.key?(:with)
+
+          if args.include?(:all)
+            set(:rescue_all, true)
+            imbue :all_rescue_handler, handler
+          else
+            handler_type =
+                case options[:rescue_subclasses]
+                when nil, true
+                  :rescue_handlers
+                else
+                  :base_only_rescue_handlers
+                end
+
+            imbue handler_type, Hash[args.map { |arg| [arg, handler] }]
+          end
+
+          imbue(:rescue_options, options)
+        end
+
+        # Allows you to specify a default representation entity for a
+        # class. This allows you to map your models to their respective
+        # entities once and then simply call `present` with the model.
+        #
+        # @example
+        #   class ExampleAPI < Grape::API
+        #     represent User, with: Entity::User
+        #
+        #     get '/me' do
+        #       present current_user # with: Entity::User is assumed
+        #     end
+        #   end
+        #
+        # Note that Grape will automatically go up the class ancestry to
+        # try to find a representing entity, so if you, for example, define
+        # an entity to represent `Object` then all presented objects will
+        # bubble up and utilize the entity provided on that `represent` call.
+        #
+        # @param model_class [Class] The model class that will be represented.
+        # @option options [Class] :with The entity class that will represent the model.
+        def represent(model_class, options)
+          raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with] && options[:with].is_a?(Class)
+          imbue(:representations, model_class => options[:with])
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/routing.rb

@@ -0,0 +1,172 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Routing
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        attr_reader :endpoints, :routes, :route_set
+
+        # Specify an API version.
+        #
+        # @example API with legacy support.
+        #   class MyAPI < Grape::API
+        #     version 'v2'
+        #
+        #     get '/main' do
+        #       {some: 'data'}
+        #     end
+        #
+        #     version 'v1' do
+        #       get '/main' do
+        #         {legacy: 'data'}
+        #       end
+        #     end
+        #   end
+        #
+        def version(*args, &block)
+          if args.any?
+            options = args.pop if args.last.is_a? Hash
+            options ||= {}
+            options = { using: :path }.merge(options)
+
+            raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.key?(:vendor)
+
+            @versions = versions | args
+            nest(block) do
+              set(:version, args)
+              set(:version_options, options)
+            end
+          end
+
+          @versions.last unless @versions.nil?
+        end
+
+        # Define a root URL prefix for your entire API.
+        def prefix(prefix = nil)
+          prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
+        end
+
+        # Do not route HEAD requests to GET requests automatically
+        def do_not_route_head!
+          set(:do_not_route_head, true)
+        end
+
+        # Do not automatically route OPTIONS
+        def do_not_route_options!
+          set(:do_not_route_options, true)
+        end
+
+        def mount(mounts)
+          mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
+          mounts.each_pair do |app, path|
+            if app.respond_to?(:inherit_settings, true)
+              app_settings = settings.clone
+              mount_path = Rack::Mount::Utils.normalize_path([settings[:mount_path], path].compact.join("/"))
+              app_settings.set :mount_path, mount_path
+              app.inherit_settings(app_settings)
+            end
+            endpoints << Grape::Endpoint.new(
+                settings.clone,
+                method: :any,
+                path: path,
+                app: app
+            )
+          end
+        end
+
+        # Defines a route that will be recognized
+        # by the Grape API.
+        #
+        # @param methods [HTTP Verb] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
+        # @param paths [String] One or more strings representing the URL segment(s) for this route.
+        #
+        # @example Defining a basic route.
+        #   class MyAPI < Grape::API
+        #     route(:any, '/hello') do
+        #       {hello: 'world'}
+        #     end
+        #   end
+        def route(methods, paths = ['/'], route_options = {}, &block)
+          endpoint_options = {
+            method: methods,
+            path: paths,
+            route_options: (@namespace_description || {}).deep_merge(@last_description || {}).deep_merge(route_options || {})
+          }
+          endpoints << Grape::Endpoint.new(settings.clone, endpoint_options, &block)
+
+          @last_description = nil
+          reset_validations!
+        end
+
+        def get(paths = ['/'], options = {}, &block)
+          route('GET', paths, options, &block)
+        end
+
+        def post(paths = ['/'], options = {}, &block)
+          route('POST', paths, options, &block)
+        end
+
+        def put(paths = ['/'], options = {}, &block)
+          route('PUT', paths, options, &block)
+        end
+
+        def head(paths = ['/'], options = {}, &block)
+          route('HEAD', paths, options, &block)
+        end
+
+        def delete(paths = ['/'], options = {}, &block)
+          route('DELETE', paths, options, &block)
+        end
+
+        def options(paths = ['/'], options = {}, &block)
+          route('OPTIONS', paths, options, &block)
+        end
+
+        def patch(paths = ['/'], options = {}, &block)
+          route('PATCH', paths, options, &block)
+        end
+
+        def namespace(space = nil, options = {},  &block)
+          if space || block_given?
+            previous_namespace_description = @namespace_description
+            @namespace_description = (@namespace_description || {}).deep_merge(@last_description || {})
+            @last_description = nil
+            nest(block) do
+              set(:namespace, Namespace.new(space, options)) if space
+            end
+            @namespace_description = previous_namespace_description
+          else
+            Namespace.joined_space_path(settings)
+          end
+        end
+
+        alias_method :group, :namespace
+        alias_method :resource, :namespace
+        alias_method :resources, :namespace
+        alias_method :segment, :namespace
+
+        # An array of API routes.
+        def routes
+          @routes ||= prepare_routes
+        end
+
+        # Thie method allows you to quickly define a parameter route segment
+        # in your API.
+        #
+        # @param param [Symbol] The name of the parameter you wish to declare.
+        # @option options [Regexp] You may supply a regular expression that the declared parameter must meet.
+        def route_param(param, options = {}, &block)
+          options = options.dup
+          options[:requirements] = { param.to_sym => options[:requirements] } if options[:requirements].is_a?(Regexp)
+          namespace(":#{param}", options, &block)
+        end
+
+        def versions
+          @versions ||= []
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/validations.rb

@@ -0,0 +1,29 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Validations
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def reset_validations!
+          settings.peek[:declared_params] = []
+          settings.peek[:validations] = []
+        end
+
+        def params(&block)
+          Grape::Validations::ParamsScope.new(api: self, type: Hash, &block)
+        end
+
+        def document_attribute(names, opts)
+          @last_description ||= {}
+          @last_description[:params] ||= {}
+          Array(names).each do |name|
+            @last_description[:params][name[:full_name].to_s] ||= {}
+            @last_description[:params][name[:full_name].to_s].merge!(opts)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/endpoint.rb

@@ -7,6 +7,8 @@ module Grape
     attr_accessor :block, :source, :options, :settings
     attr_reader :env, :request, :headers, :params
 
+    include Grape::DSL::InsideRoute
+
     class << self
       def before_each(new_setup = false, &block)
         if new_setup == false
@@ -49,6 +51,8 @@ module Grape
       require_option(options, :method)
 
       @settings = settings
+      @settings[:default_error_status] ||= 500
+
       @options = options
 
       @options[:path] = Array(options[:path])
@@ -92,7 +96,7 @@ module Grape
             route_set.add_route(self, {
                                   path_info: route.route_compiled,
                                   request_method: method
-            },  route_info: route)
+                                },  route_info: route)
           end
         end
       end
@@ -169,214 +173,6 @@ module Grape
       end
     end
 
-    # A filtering method that will return a hash
-    # consisting only of keys that have been declared by a
-    # `params` statement against the current/target endpoint or parent
-    # namespaces
-    #
-    # @param params [Hash] The initial hash to filter. Usually this will just be `params`
-    # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
-    # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
-    # you want only to return params declared against the current/target endpoint
-    def declared(params, options = {}, declared_params = nil)
-      options[:include_missing] = true unless options.key?(:include_missing)
-      options[:include_parent_namespaces] = true unless options.key?(:include_parent_namespaces)
-      if declared_params.nil?
-        declared_params = !options[:include_parent_namespaces] ? settings[:declared_params] :
-          settings.gather(:declared_params)
-      end
-
-      unless declared_params
-        raise ArgumentError, "Tried to filter for declared parameters but none exist."
-      end
-
-      if params.is_a? Array
-        params.map do |param|
-          declared(param || {}, options, declared_params)
-        end
-      else
-        declared_params.inject({}) do |hash, key|
-          key = { key => nil } unless key.is_a? Hash
-
-          key.each_pair do |parent, children|
-            output_key = options[:stringify] ? parent.to_s : parent.to_sym
-            if params.key?(parent) || options[:include_missing]
-              hash[output_key] = if children
-                                   declared(params[parent] || {}, options, Array(children))
-                                 else
-                                   params[parent]
-                                 end
-            end
-          end
-
-          hash
-        end
-      end
-    end
-
-    # The API version as specified in the URL.
-    def version
-      env['api.version']
-    end
-
-    # End the request and display an error to the
-    # end user with the specified message.
-    #
-    # @param message [String] The message to display.
-    # @param status [Integer] the HTTP Status Code. Defaults to default_error_status, 500 if not set.
-    def error!(message, status = nil, headers = nil)
-      status = settings[:default_error_status] unless status
-      throw :error, message: message, status: status, headers: headers
-    end
-
-    # Redirect to a new url.
-    #
-    # @param url [String] The url to be redirect.
-    # @param options [Hash] The options used when redirect.
-    #                       :permanent, default true.
-    def redirect(url, options = {})
-      merged_options = { permanent: false }.merge(options)
-      if merged_options[:permanent]
-        status 301
-      else
-        if env['HTTP_VERSION'] == 'HTTP/1.1' && request.request_method.to_s.upcase != "GET"
-          status 303
-        else
-          status 302
-        end
-      end
-      header "Location", url
-      body ""
-    end
-
-    # Set or retrieve the HTTP status code.
-    #
-    # @param status [Integer] The HTTP Status Code to return for this request.
-    def status(status = nil)
-      if status
-        @status = status
-      else
-        return @status if @status
-        case request.request_method.to_s.upcase
-        when 'POST'
-          201
-        else
-          200
-        end
-      end
-    end
-
-    # Set an individual header or retrieve
-    # all headers that have been set.
-    def header(key = nil, val = nil)
-      if key
-        val ? @header[key.to_s] = val : @header.delete(key.to_s)
-      else
-        @header
-      end
-    end
-
-    # Set response content-type
-    def content_type(val)
-      header('Content-Type', val)
-    end
-
-    # Set or get a cookie
-    #
-    # @example
-    #   cookies[:mycookie] = 'mycookie val'
-    #   cookies['mycookie-string'] = 'mycookie string val'
-    #   cookies[:more] = { value: '123', expires: Time.at(0) }
-    #   cookies.delete :more
-    #
-    def cookies
-      @cookies ||= Cookies.new
-    end
-
-    # Allows you to define the response body as something other than the
-    # return value.
-    #
-    # @example
-    #   get '/body' do
-    #     body "Body"
-    #     "Not the Body"
-    #   end
-    #
-    #   GET /body # => "Body"
-    def body(value = nil)
-      if value
-        @body = value
-      else
-        @body
-      end
-    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
-    # added benefit of automatically passing along environment
-    # and version information to the serialization, making it
-    # very easy to do conditional exposures. See Entity docs
-    # for more info.
-    #
-    # @example
-    #
-    #   get '/users/:id' do
-    #     present User.find(params[:id]),
-    #       with: API::Entities::User,
-    #       admin: current_user.admin?
-    #   end
-    def present(*args)
-      options = args.count > 1 ? args.extract_options! : {}
-      key, object = if args.count == 2 && args.first.is_a?(Symbol)
-                      args
-                    else
-                      [nil, args.first]
-                    end
-      entity_class = options.delete(:with)
-
-      if entity_class.nil?
-        # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
-        object_class = if object.respond_to?(:klass)
-                         object.klass
-                       else
-                         object.respond_to?(:first) ? object.first.class : object.class
-                       end
-
-        object_class.ancestors.each do |potential|
-          entity_class ||= (settings[:representations] || {})[potential]
-        end
-
-        entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-      end
-
-      root = options.delete(:root)
-
-      representation = if entity_class
-                         embeds = { env: env }
-                         embeds[:version] = env['api.version'] if env['api.version']
-                         entity_class.represent(object, embeds.merge(options))
-                       else
-                         object
-                       end
-
-      representation = { root => representation } if root
-      representation = (@body || {}).merge(key => representation) if key
-      body representation
-    end
-
-    # Returns route information for the current request.
-    #
-    # @example
-    #
-    #   desc "Returns the route description."
-    #   get '/' do
-    #     route.route_description
-    #   end
-    def route
-      env["rack.routing_args"][:route_info]
-    end
-
     # Return the collection of endpoints within this endpoint.
     # This is the case when an Grape::API mounts another Grape::API.
     def endpoints
@@ -435,7 +231,7 @@ module Grape
       b.use Grape::Middleware::Error,
             format: settings[:format],
             content_types: settings[:content_types],
-            default_status: settings[:default_error_status] || 500,
+            default_status: settings[:default_error_status],
             rescue_all: settings[:rescue_all],
             default_error_formatter: settings[:default_error_formatter],
             error_formatters: settings[:error_formatters],
@@ -454,22 +250,6 @@ module Grape
         end
       end
 
-      if settings[:auth]
-        auth_proc         = settings[:auth][:proc]
-        auth_proc_context = self
-        auth_middleware   = {
-          http_basic:   { class: Rack::Auth::Basic,       args: [settings[:auth][:realm]] },
-          http_digest:  { class: Rack::Auth::Digest::MD5, args: [settings[:auth][:realm], settings[:auth][:opaque]] }
-        }[settings[:auth][:type]]
-
-        # evaluate auth proc in context of endpoint
-        if auth_middleware
-          b.use auth_middleware[:class], *auth_middleware[:args] do |*args|
-            auth_proc_context.instance_exec(*args, &auth_proc)
-          end
-        end
-      end
-
       if settings[:version]
         b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]),
               versions: settings[:version] ? settings[:version].flatten : nil,