grape 1.8.0 → 4.0.1

data/lib/grape/{util/env.rb → env.rb}

@@ -11,15 +11,15 @@ module Grape
     API_VENDOR = 'api.vendor'
     API_FORMAT = 'api.format'
 
-    RACK_INPUT = 'rack.input'
-    RACK_REQUEST_QUERY_HASH = 'rack.request.query_hash'
-    RACK_REQUEST_FORM_HASH = 'rack.request.form_hash'
-    RACK_REQUEST_FORM_INPUT = 'rack.request.form_input'
-
-    GRAPE_REQUEST = 'grape.request'
-    GRAPE_REQUEST_HEADERS = 'grape.request.headers'
-    GRAPE_REQUEST_PARAMS = 'grape.request.params'
+    GRAPE_NORMALIZED_PATH = 'grape.normalized_path'
     GRAPE_ROUTING_ARGS = 'grape.routing_args'
     GRAPE_ALLOWED_METHODS = 'grape.allowed_methods'
+    GRAPE_EXCEPTION = 'grape.exception'
+
+    # Not a Grape-owned key: the de-facto convention for an exception that was
+    # handled rather than raised, which is how error trackers find one they
+    # never saw propagate. sentry-ruby, for one, collects
+    # +env['rack.exception'] || env['sinatra.error']+.
+    RACK_EXCEPTION = 'rack.exception'
   end
 end

data/lib/grape/error_formatter/base.rb

@@ -2,36 +2,72 @@
 
 module Grape
   module ErrorFormatter
-    module Base
-      def present(message, env)
-        present_options = {}
-        presented_message = message
-        if presented_message.is_a?(Hash)
-          presented_message = presented_message.dup
-          present_options[:with] = presented_message.delete(:with)
+    class Base
+      class << self
+        # Custom error formatters override +call+. The +error+ is a frozen
+        # {Grape::Exceptions::ErrorResponse} carrying +status+/+message+/
+        # +headers+/+backtrace+/+original_exception+. +env+ is the Rack env
+        # (needed by entity-presenter resolution). +include_backtrace+ and
+        # +include_original_exception+ are the request-time toggles set by
+        # +rescue_from+; the base implementation embeds the corresponding
+        # fields in the response body when they are true.
+        def call(error:, env: nil, include_backtrace: false, include_original_exception: false)
+          wrapped_message = wrap_message(present(error.message, env))
+          if wrapped_message.is_a?(Hash)
+            wrapped_message[:backtrace] = error.backtrace if include_backtrace && error.backtrace.present?
+            wrapped_message[:original_exception] = error.original_exception.inspect if include_original_exception && error.original_exception
+          end
+
+          format_structured_message(wrapped_message)
         end
 
-        presenter = env[Grape::Env::API_ENDPOINT].entity_class_for_obj(presented_message, present_options)
+        def present(message, env)
+          # error! accepts a message hash with an optional :with key specifying the entity presenter.
+          # Extract it here so the presenter can be resolved and the key is not serialized in the response.
+          # See spec/integration/grape_entity/entity_spec.rb for examples.
+          with = nil
+          payload = message
+          if message.is_a?(Hash) && message.key?(:with)
+            payload = message.dup
+            with = payload.delete(:with)
+          end
 
-        unless presenter || env[Grape::Env::GRAPE_ROUTING_ARGS].nil?
-          # env['api.endpoint'].route does not work when the error occurs within a middleware
-          # the Endpoint does not have a valid env at this moment
-          http_codes = env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info].http_codes || []
+          presenter = with || env[Grape::Env::API_ENDPOINT].entity_class_for_obj(payload)
 
-          found_code = http_codes.find do |http_code|
-            (http_code[0].to_i == env[Grape::Env::API_ENDPOINT].status) && http_code[2].respond_to?(:represent)
-          end if env[Grape::Env::API_ENDPOINT].request
+          unless presenter || env[Grape::Env::GRAPE_ROUTING_ARGS].nil?
+            # env['api.endpoint'].route does not work when the error occurs within a middleware
+            # the Endpoint does not have a valid env at this moment
+            http_codes = env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info].http_codes || []
+            found_code = http_codes.find do |http_code|
+              (http_code[0].to_i == env[Grape::Env::API_ENDPOINT].status) && http_code[2].respond_to?(:represent)
+            end if env[Grape::Env::API_ENDPOINT].request
 
-          presenter = found_code[2] if found_code
-        end
+            presenter = found_code[2] if found_code
+          end
+
+          return payload unless presenter
 
-        if presenter
-          embeds = { env: env }
+          embeds = { env: }
           embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
-          presented_message = presenter.represent(presented_message, embeds).serializable_hash
+          presenter.represent(payload, embeds).serializable_hash
+        end
+
+        def wrap_message(message)
+          return message if message.is_a?(Hash)
+
+          { message: }
+        end
+
+        def format_structured_message(_structured_message)
+          raise NotImplementedError
         end
 
-        presented_message
+        private
+
+        def inherited(klass)
+          super
+          ErrorFormatter.register(klass)
+        end
       end
     end
   end

data/lib/grape/error_formatter/json.rb

@@ -2,27 +2,25 @@
 
 module Grape
   module ErrorFormatter
-    module Json
-      extend Base
-
+    class Json < Base
       class << self
-        def call(message, backtrace, options = {}, env = nil, original_exception = nil)
-          result = wrap_message(present(message, env))
-
-          rescue_options = options[:rescue_options] || {}
-          result = result.merge(backtrace: backtrace) if rescue_options[:backtrace] && backtrace && !backtrace.empty?
-          result = result.merge(original_exception: original_exception.inspect) if rescue_options[:original_exception] && original_exception
-          ::Grape::Json.dump(result)
+        def format_structured_message(structured_message)
+          ::Grape::Json.dump(structured_message)
         end
 
         private
 
         def wrap_message(message)
-          if message.is_a?(Exceptions::ValidationErrors) || message.is_a?(Hash)
-            message
-          else
-            { error: ensure_utf8(message) }
-          end
+          # Use +is_a?+ rather than +case/when+ here. +case/when Hash+ matches via
+          # +Module#===+, a C-level real-class check that ignores delegation, so a
+          # +SimpleDelegator+ wrapping a Hash (e.g. the +OutputBuilder+ returned by
+          # +Grape::Entity#serializable_hash+ when an error is presented via an entity)
+          # would fall through and be wrapped in a spurious +{ error: ... }+ envelope.
+          # +is_a?+ is forwarded by the delegator to the wrapped Hash, so it matches.
+          return message if message.is_a?(Hash)
+          return message.as_json if message.is_a?(Exceptions::ValidationErrors)
+
+          { error: ensure_utf8(message) }
         end
 
         def ensure_utf8(message)

data/lib/grape/error_formatter/serializable_hash.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Grape
+  module ErrorFormatter
+    class SerializableHash < Json; end
+  end
+end

data/lib/grape/error_formatter/txt.rb

@@ -2,25 +2,19 @@
 
 module Grape
   module ErrorFormatter
-    module Txt
-      extend Base
-
-      class << self
-        def call(message, backtrace, options = {}, env = nil, original_exception = nil)
-          message = present(message, env)
-
-          result = message.is_a?(Hash) ? ::Grape::Json.dump(message) : message
-          rescue_options = options[:rescue_options] || {}
-          if rescue_options[:backtrace] && backtrace && !backtrace.empty?
-            result += "\r\n backtrace:"
-            result += backtrace.join("\r\n ")
-          end
-          if rescue_options[:original_exception] && original_exception
-            result += "\r\n original exception:"
-            result += "\r\n #{original_exception.inspect}"
-          end
-          result
+    class Txt < Base
+      def self.format_structured_message(structured_message)
+        message = structured_message[:message] || Grape::Json.dump(structured_message)
+        final_message = Array.wrap(message)
+        if structured_message.key?(:backtrace)
+          final_message << 'backtrace:'
+          final_message.concat(structured_message[:backtrace])
+        end
+        if structured_message.key?(:original_exception)
+          final_message << 'original exception:'
+          final_message << structured_message[:original_exception]
         end
+        final_message.join("\r\n ")
       end
     end
   end

data/lib/grape/error_formatter/xml.rb

@@ -2,19 +2,9 @@
 
 module Grape
   module ErrorFormatter
-    module Xml
-      extend Base
-
-      class << self
-        def call(message, backtrace, options = {}, env = nil, original_exception = nil)
-          message = present(message, env)
-
-          result = message.is_a?(Hash) ? message : { message: message }
-          rescue_options = options[:rescue_options] || {}
-          result = result.merge(backtrace: backtrace) if rescue_options[:backtrace] && backtrace && !backtrace.empty?
-          result = result.merge(original_exception: original_exception.inspect) if rescue_options[:original_exception] && original_exception
-          result.respond_to?(:to_xml) ? result.to_xml(root: :error) : result.to_s
-        end
+    class Xml < Base
+      def self.format_structured_message(structured_message)
+        structured_message.respond_to?(:to_xml) ? structured_message.to_xml(root: :error) : structured_message.to_s
       end
     end
   end

data/lib/grape/error_formatter.rb

@@ -2,34 +2,18 @@
 
 module Grape
   module ErrorFormatter
-    extend Util::Registrable
+    extend Grape::Util::Registry
 
-    class << self
-      def builtin_formatters
-        @builtin_formatters ||= {
-          serializable_hash: Grape::ErrorFormatter::Json,
-          json: Grape::ErrorFormatter::Json,
-          jsonapi: Grape::ErrorFormatter::Json,
-          txt: Grape::ErrorFormatter::Txt,
-          xml: Grape::ErrorFormatter::Xml
-        }
-      end
+    module_function
 
-      def formatters(**options)
-        builtin_formatters.merge(default_elements).merge!(options[:error_formatters] || {})
-      end
+    # Answers nil when nothing is registered for the format, the way
+    # +Parser.parser_for+ does. What to fall back to then is the API's own
+    # +default_error_formatter+, which is the caller's state rather than the
+    # registry's: +Middleware::Error+ holds it and applies it.
+    def formatter_for(format, error_formatters = nil)
+      return error_formatters[format] if error_formatters&.key?(format)
 
-      def formatter_for(api_format, **options)
-        spec = formatters(**options)[api_format]
-        case spec
-        when nil
-          options[:default_error_formatter] || Grape::ErrorFormatter::Txt
-        when Symbol
-          method(spec)
-        else
-          spec
-        end
-      end
+      registry[format]
     end
   end
 end

data/lib/grape/exceptions/base.rb

@@ -3,13 +3,13 @@
 module Grape
   module Exceptions
     class Base < StandardError
-      BASE_MESSAGES_KEY = 'grape.errors.messages'
-      BASE_ATTRIBUTES_KEY = 'grape.errors.attributes'
-      FALLBACK_LOCALE = :en
+      include Grape::Util::Translation
+
+      MESSAGE_STEPS = %w[problem summary resolution].to_h { |s| [s.to_sym, s.capitalize] }.freeze
 
       attr_reader :status, :headers
 
-      def initialize(status: nil, message: nil, headers: nil, **_options)
+      def initialize(status: nil, message: nil, headers: nil)
         super(message)
 
         @status  = status
@@ -17,70 +17,34 @@ module Grape
       end
 
       def [](index)
-        send index
+        __send__ index
       end
 
-      protected
-
-      # TODO: translate attribute first
-      # if BASE_ATTRIBUTES_KEY.key respond to a string message, then short_message is returned
-      # if BASE_ATTRIBUTES_KEY.key respond to a Hash, means it may have problem , summary and resolution
-      def compose_message(key, **attributes)
-        short_message = translate_message(key, **attributes)
-        if short_message.is_a? Hash
-          @problem = problem(key, **attributes)
-          @summary = summary(key, **attributes)
-          @resolution = resolution(key, **attributes)
-          [['Problem', @problem], ['Summary', @summary], ['Resolution', @resolution]].each_with_object(+'') do |detail_array, message|
-            message << "\n#{detail_array[0]}:\n  #{detail_array[1]}" unless detail_array[1].blank?
-            message
-          end
-        else
-          short_message
-        end
-      end
+      private
 
-      def problem(key, **attributes)
-        translate_message("#{key}.problem".to_sym, **attributes)
-      end
+      def compose_message(key, **)
+        short_message = translate_message(key, **)
+        return short_message unless short_message.is_a?(Hash)
 
-      def summary(key, **attributes)
-        translate_message("#{key}.summary".to_sym, **attributes)
-      end
+        MESSAGE_STEPS.filter_map do |step, label|
+          next unless short_message.key?(step)
 
-      def resolution(key, **attributes)
-        translate_message("#{key}.resolution".to_sym, **attributes)
+          detail = translate_message(:"#{key}.#{step}", **)
+          "\n#{label}:\n  #{detail}" if detail.present?
+        end.join
       end
 
-      def translate_attributes(keys, **options)
-        keys.map do |key|
-          translate("#{BASE_ATTRIBUTES_KEY}.#{key}", default: key, **options)
-        end.join(', ')
-      end
-
-      def translate_message(key, **options)
-        case key
+      def translate_message(translation_key, **)
+        case translation_key
         when Symbol
-          translate("#{BASE_MESSAGES_KEY}.#{key}", default: '', **options)
+          translate(translation_key, **)
+        when Hash
+          translation_key => { key:, **opts }
+          translate(key, **opts)
         when Proc
-          key.call
-        else
-          key
-        end
-      end
-
-      def translate(key, **options)
-        options = options.dup
-        options[:default] &&= options[:default].to_s
-        message = ::I18n.translate(key, **options)
-        message.presence || fallback_message(key, **options)
-      end
-
-      def fallback_message(key, **options)
-        if ::I18n.enforce_available_locales && ::I18n.available_locales.exclude?(FALLBACK_LOCALE)
-          key
+          translation_key.call
         else
-          ::I18n.translate(key, locale: FALLBACK_LOCALE, **options)
+          translation_key
         end
       end
     end

data/lib/grape/exceptions/error_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    # Value object representing the payload thrown via `throw :error, ...`
+    # and consumed by `Middleware::Error#error_response`. Replaces the
+    # implicit-schema Hash that previously circulated between throw sites
+    # and the error middleware.
+    ErrorResponse = Data.define(:status, :message, :headers, :backtrace, :original_exception) do
+      def initialize(status: nil, message: nil, headers: nil, backtrace: nil, original_exception: nil)
+        super
+      end
+
+      def to_s
+        "#<#{self.class.name} status=#{status.inspect} message=#{message.inspect} headers=#{headers.inspect}>"
+      end
+
+      # The backtrace is deliberately left unset: +Exception#backtrace+ builds
+      # the whole Array of location strings, and the response only renders one
+      # when the API asked for it. The exception travels along, so
+      # +Middleware::Error#error_response+ can still materialize it there.
+      def self.from_exception(exception)
+        new(
+          status: exception.status,
+          message: exception.message,
+          headers: exception.headers,
+          original_exception: exception
+        )
+      end
+
+      # Normalize heterogeneous inputs into an ErrorResponse. Preserves the
+      # public contract that users can still `throw :error, hash` from their
+      # own middleware or `rescue_from` handlers.
+      def self.coerce(input)
+        case input
+        when ErrorResponse
+          input
+        when Grape::Exceptions::Base
+          from_exception(input)
+        when Hash
+          new(**input.slice(:status, :message, :headers, :backtrace, :original_exception))
+        else
+          new
+        end
+      end
+    end
+  end
+end

data/lib/grape/exceptions/incompatible_option_values.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class IncompatibleOptionValues < Base
       def initialize(option1, value1, option2, value2)
-        super(message: compose_message(:incompatible_option_values, option1: option1, value1: value1, option2: option2, value2: value2))
+        super(message: compose_message(:incompatible_option_values, option1:, value1:, option2:, value2:))
       end
     end
   end

data/lib/grape/exceptions/internal_server_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    # Raised internally when a +rescue_from+ handler itself raises an
+    # unrecognised exception. The framework substitutes the original
+    # exception with this safe stand-in for rendering, while preserving
+    # the original on +env[Grape::Env::GRAPE_EXCEPTION]+ for upstream
+    # observability (loggers, error trackers, etc.).
+    class InternalServerError < Base
+      def initialize
+        super(status: 500, message: compose_message(:internal_server_error))
+      end
+    end
+  end
+end

data/lib/grape/exceptions/invalid_accept_header.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class InvalidAcceptHeader < Base
       def initialize(message, headers)
-        super(message: compose_message(:invalid_accept_header, message: message), status: 406, headers: headers)
+        super(message: compose_message(:invalid_accept_header, message:), status: 406, headers:)
       end
     end
   end

data/lib/grape/exceptions/invalid_formatter.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class InvalidFormatter < Base
       def initialize(klass, to_format)
-        super(message: compose_message(:invalid_formatter, klass: klass, to_format: to_format))
+        super(message: compose_message(:invalid_formatter, klass:, to_format:))
       end
     end
   end

data/lib/grape/exceptions/invalid_message_body.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class InvalidMessageBody < Base
       def initialize(body_format)
-        super(message: compose_message(:invalid_message_body, body_format: body_format), status: 400)
+        super(message: compose_message(:invalid_message_body, body_format:), status: 400)
       end
     end
   end

data/lib/grape/exceptions/invalid_version_header.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class InvalidVersionHeader < Base
       def initialize(message, headers)
-        super(message: compose_message(:invalid_version_header, message: message), status: 406, headers: headers)
+        super(message: compose_message(:invalid_version_header, message:), status: 406, headers:)
       end
     end
   end

data/lib/grape/exceptions/invalid_versioner_option.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class InvalidVersionerOption < Base
       def initialize(strategy)
-        super(message: compose_message(:invalid_versioner_option, strategy: strategy))
+        super(message: compose_message(:invalid_versioner_option, strategy:))
       end
     end
   end

data/lib/grape/exceptions/method_not_allowed.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class MethodNotAllowed < Base
       def initialize(headers)
-        super(message: '405 Not Allowed', status: 405, headers: headers)
+        super(message: '405 Not Allowed', status: 405, headers:)
       end
     end
   end

data/lib/grape/exceptions/missing_group_type.rb

@@ -9,5 +9,3 @@ module Grape
     end
   end
 end
-
-Grape::Exceptions::MissingGroupTypeError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Grape::Exceptions::MissingGroupTypeError', 'Grape::Exceptions::MissingGroupType')

data/lib/grape/exceptions/missing_mime_type.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class MissingMimeType < Base
       def initialize(new_format)
-        super(message: compose_message(:missing_mime_type, new_format: new_format))
+        super(message: compose_message(:missing_mime_type, new_format:))
       end
     end
   end

data/lib/grape/exceptions/request_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    class RequestError < Base
+      def initialize(status: 400)
+        super(message: $ERROR_INFO&.message, status:)
+      end
+    end
+  end
+end

data/lib/grape/exceptions/unknown_auth_strategy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    class UnknownAuthStrategy < Base
+      def initialize(strategy:)
+        super(message: compose_message(:unknown_auth_strategy, strategy:))
+      end
+    end
+  end
+end

data/lib/grape/exceptions/unknown_error_formatter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    class UnknownErrorFormatter < Base
+      def initialize(error_formatter_type)
+        super(message: compose_message(:unknown_error_formatter, error_formatter_type:))
+      end
+    end
+  end
+end

data/lib/grape/exceptions/unknown_parameter.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class UnknownParameter < Base
       def initialize(param)
-        super(message: compose_message(:unknown_parameter, param: param))
+        super(message: compose_message(:unknown_parameter, param:))
       end
     end
   end

data/lib/grape/exceptions/unknown_params_builder.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    class UnknownParamsBuilder < Base
+      def initialize(params_builder_type)
+        super(message: compose_message(:unknown_params_builder, params_builder_type:))
+      end
+    end
+  end
+end

data/lib/grape/exceptions/unknown_validator.rb

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class UnknownValidator < Base
       def initialize(validator_type)
-        super(message: compose_message(:unknown_validator, validator_type: validator_type))
+        super(message: compose_message(:unknown_validator, validator_type:))
       end
     end
   end

data/lib/grape/exceptions/unsupported_group_type.rb

@@ -9,5 +9,3 @@ module Grape
     end
   end
 end
-
-Grape::Exceptions::UnsupportedGroupTypeError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Grape::Exceptions::UnsupportedGroupTypeError', 'Grape::Exceptions::UnsupportedGroupType')