grape 0.1.1 → 2.4.0

data/lib/grape/dsl/logger.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Logger
+      include Grape::DSL::Settings
+
+      attr_writer :logger
+
+      # 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)
+        else
+          global_setting(:logger) || global_setting(:logger, ::Logger.new($stdout))
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/middleware.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Middleware
+      extend ActiveSupport::Concern
+
+      include Grape::DSL::Configuration
+
+      module ClassMethods
+        # Apply a custom middleware to the API. Applies
+        # to the current namespace and any children, but
+        # not parents.
+        #
+        # @param middleware_class [Class] The class of the middleware you'd like
+        #   to inject.
+        def use(middleware_class, *args, &block)
+          arr = [:use, middleware_class, *args]
+          arr << block if block
+
+          namespace_stackable(:middleware, arr)
+        end
+
+        def insert(*args, &block)
+          arr = [:insert, *args]
+          arr << block if block
+
+          namespace_stackable(:middleware, arr)
+        end
+
+        def insert_before(*args, &block)
+          arr = [:insert_before, *args]
+          arr << block if block
+
+          namespace_stackable(:middleware, arr)
+        end
+
+        def insert_after(*args, &block)
+          arr = [:insert_after, *args]
+          arr << block if block
+
+          namespace_stackable(:middleware, arr)
+        end
+
+        # Retrieve an array of the middleware classes
+        # and arguments that are currently applied to the
+        # application.
+        def middleware
+          namespace_stackable(:middleware) || []
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/parameters.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+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
+
+      # Set the module used to build the request.params.
+      #
+      # @param build_with the ParamBuilder module to use when building request.params
+      #   Available builders are:
+      #
+      #     * Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder (default)
+      #     * Grape::Extensions::Hash::ParamBuilder
+      #     * Grape::Extensions::Hashie::Mash::ParamBuilder
+      #
+      # @example
+      #
+      #     require 'grape/extenstions/hashie_mash'
+      #     class API < Grape::API
+      #       desc "Get collection"
+      #       params do
+      #         build_with :hashie_mash
+      #         requires :user_id, type: Integer
+      #       end
+      #       get do
+      #         params['user_id']
+      #       end
+      #     end
+      def build_with(build_with)
+        @api.namespace_inheritable(:build_params_with, build_with)
+      end
+
+      # Include reusable params rules among current.
+      # You can define reusable params with helpers method.
+      #
+      # @example
+      #
+      #     class API < Grape::API
+      #       helpers do
+      #         params :pagination do
+      #           optional :page, type: Integer
+      #           optional :per_page, type: Integer
+      #         end
+      #       end
+      #
+      #       desc "Get collection"
+      #       params do
+      #         use :pagination
+      #       end
+      #       get do
+      #         Collection.page(params[:page]).per(params[:per_page])
+      #       end
+      #     end
+      def use(*names)
+        named_params = @api.namespace_stackable_with_hash(:named_params) || {}
+        options = names.extract_options!
+        names.each do |name|
+          params_block = named_params.fetch(name) do
+            raise "Params :#{name} not found!"
+          end
+
+          if options.empty?
+            instance_exec(options, &params_block)
+          else
+            instance_exec(**options, &params_block)
+          end
+        end
+      end
+      alias use_scope use
+      alias includes use
+
+      # Require one or more parameters for the current endpoint.
+      #
+      # @param attrs list of parameters 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::Validations::Types} for a list of
+      #   types that are supported automatically. Custom classes may be used
+      #   where they define a class-level `::parse` method, or in conjunction
+      #   with the `:coerce_with` parameter. `JSON` may be supplied to denote
+      #   `JSON`-formatted objects or arrays of objects. `Array[JSON]` accepts
+      #   the same values as `JSON` but will wrap single objects in an `Array`.
+      # @option attrs :types [Array<Class>] may be supplied in place of +:type+
+      #   to declare an attribute that has multiple allowed types. See
+      #   {Validations::Types::MultipleTypeCoercer} for more details on coercion
+      #   and validation rules for variant-type parameters.
+      # @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
+      # @option attrs :coerce_with [#parse, #call] method to be used when coercing
+      #   the parameter to the type named by `attrs[:type]`. Any class or object
+      #   that defines `::parse` or `::call` may be used.
+      #
+      # @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
+
+        opts = attrs.extract_options!.clone
+        opts[:presence] = { value: true, message: opts[:message] }
+        opts = @group.deep_merge(opts) if instance_variable_defined?(:@group) && @group
+
+        if opts[:using]
+          require_required_and_optional_fields(attrs.first, opts)
+        else
+          validate_attributes(attrs, opts, &block)
+          block ? new_scope(orig_attrs, &block) : push_declared_params(attrs, opts.slice(:as))
+        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
+
+        opts = attrs.extract_options!.clone
+        type = opts[:type]
+        opts = @group.deep_merge(opts) if instance_variable_defined?(:@group) && @group
+
+        # check type for optional parameter group
+        if attrs && block
+          raise Grape::Exceptions::MissingGroupType if type.nil?
+          raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
+        end
+
+        if opts[:using]
+          require_optional_fields(attrs.first, opts)
+        else
+          validate_attributes(attrs, opts, &block)
+
+          block ? new_scope(orig_attrs, true, &block) : push_declared_params(attrs, opts.slice(:as))
+        end
+      end
+
+      # Define common settings for one or more parameters
+      # @param (see #requires)
+      # @option (see #requires)
+      def with(*attrs, &block)
+        new_group_attrs = [@group, attrs.clone.first].compact.reduce(&:deep_merge)
+        new_group_scope([new_group_attrs], &block)
+      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: { value: true, message: extract_message_option(attrs) })
+      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: { value: true, message: extract_message_option(attrs) })
+      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: { value: true, message: extract_message_option(attrs) })
+      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: { value: true, message: extract_message_option(attrs) })
+      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
+      # @raise Grape::Exceptions::UnknownParameter if `attr` has not been
+      #   defined in this scope yet
+      # @yield a parameter definition DSL
+      def given(*attrs, &block)
+        attrs.each do |attr|
+          proxy_attr = first_hash_key_or_param(attr)
+          raise Grape::Exceptions::UnknownParameter.new(proxy_attr) unless declared_param?(proxy_attr)
+        end
+        new_lateral_scope(dependent_on: attrs, &block)
+      end
+
+      # Test for whether a certain parameter has been defined in this params
+      # block yet.
+      # @return [Boolean] whether the parameter has been defined
+      def declared_param?(param)
+        if lateral?
+          # Elements of @declared_params of lateral scope are pushed in @parent. So check them in @parent.
+          @parent.declared_param?(param)
+        else
+          # @declared_params also includes hashes of options and such, but those
+          # won't be flattened out.
+          @declared_params.flatten.any? do |declared_param_attr|
+            first_hash_key_or_param(declared_param_attr.key) == param
+          end
+        end
+      end
+
+      alias group requires
+
+      class EmptyOptionalValue; end # rubocop:disable Lint/EmptyClass
+
+      def map_params(params, element, is_array = false)
+        if params.is_a?(Array)
+          params.map do |el|
+            map_params(el, element, true)
+          end
+        elsif params.is_a?(Hash)
+          params[element] || (@optional && is_array ? EmptyOptionalValue : {})
+        elsif params == EmptyOptionalValue
+          EmptyOptionalValue
+        else
+          {}
+        end
+      end
+
+      # @param params [Hash] initial hash of parameters
+      # @return hash of parameters relevant for the current scope
+      # @api private
+      def params(params)
+        params = @parent.params_meeting_dependency.presence || @parent.params(params) if instance_variable_defined?(:@parent) && @parent
+        params = map_params(params, @element) if instance_variable_defined?(:@element) && @element
+        params
+      end
+
+      private
+
+      def first_hash_key_or_param(parameter)
+        parameter.is_a?(Hash) ? parameter.keys.first : parameter
+      end
+    end
+  end
+end

data/lib/grape/dsl/request_response.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module RequestResponse
+      extend ActiveSupport::Concern
+
+      include Grape::DSL::Configuration
+
+      module ClassMethods
+        # Specify the default format for the API's serializers.
+        # May be `:json` or `:txt` (default).
+        def default_format(new_format = nil)
+          namespace_inheritable(:default_format, new_format.nil? ? nil : new_format.to_sym)
+        end
+
+        # Specify the format for the API's serializers.
+        # May be `:json`, `:xml`, `:txt`, etc.
+        def format(new_format = nil)
+          return namespace_inheritable(:format) unless new_format
+
+          symbolic_new_format = new_format.to_sym
+          namespace_inheritable(:format, symbolic_new_format)
+          namespace_inheritable(:default_error_formatter, Grape::ErrorFormatter.formatter_for(symbolic_new_format))
+
+          content_type = content_types[symbolic_new_format]
+          raise Grape::Exceptions::MissingMimeType.new(new_format) unless content_type
+
+          namespace_stackable(:content_types, symbolic_new_format => content_type)
+        end
+
+        # Specify a custom formatter for a content-type.
+        def formatter(content_type, new_formatter)
+          namespace_stackable(:formatters, content_type.to_sym => new_formatter)
+        end
+
+        # Specify a custom parser for a content-type.
+        def parser(content_type, new_parser)
+          namespace_stackable(:parsers, content_type.to_sym => new_parser)
+        end
+
+        # Specify a default error formatter.
+        def default_error_formatter(new_formatter_name = nil)
+          return namespace_inheritable(:default_error_formatter) unless new_formatter_name
+
+          new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
+          namespace_inheritable(:default_error_formatter, new_formatter)
+        end
+
+        def error_formatter(format, options)
+          formatter = if options.is_a?(Hash) && options.key?(:with)
+                        options[:with]
+                      else
+                        options
+                      end
+
+          namespace_stackable(: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)
+          namespace_stackable(:content_types, key.to_sym => val)
+        end
+
+        # All available content types.
+        def content_types
+          c_types = namespace_stackable_with_hash(:content_types)
+          Grape::ContentTypes.content_types_for c_types
+        end
+
+        # Specify the default status code for errors.
+        def default_error_status(new_status = nil)
+          namespace_inheritable(:default_error_status, new_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
+            handler = block
+          end
+
+          options = args.extract_options!
+          raise ArgumentError, 'both :with option and block cannot be passed' if block && options.key?(:with)
+
+          handler ||= extract_with(options)
+
+          if args.include?(:all)
+            namespace_inheritable(:rescue_all, true)
+            namespace_inheritable(:all_rescue_handler, handler)
+          elsif args.include?(:grape_exceptions)
+            namespace_inheritable(:rescue_all, true)
+            namespace_inheritable(:rescue_grape_exceptions, true)
+            namespace_inheritable(:grape_exceptions_rescue_handler, handler)
+          else
+            handler_type =
+              case options[:rescue_subclasses]
+              when nil, true
+                :rescue_handlers
+              else
+                :base_only_rescue_handlers
+              end
+
+            namespace_reverse_stackable(handler_type, args.to_h { |arg| [arg, handler] })
+          end
+
+          namespace_stackable(: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].is_a?(Class)
+
+          namespace_stackable(:representations, model_class => options[:with])
+        end
+
+        private
+
+        def extract_with(options)
+          return unless options.key?(:with)
+
+          with_option = options.delete(:with)
+          return with_option if with_option.instance_of?(Proc)
+          return with_option.to_sym if with_option.instance_of?(Symbol) || with_option.instance_of?(String)
+
+          raise ArgumentError, "with: #{with_option.class}, expected Symbol, String or Proc"
+        end
+      end
+    end
+  end
+end