grape 2.4.0 → 4.0.1

data/lib/grape/env.rb

@@ -11,10 +11,15 @@ module Grape
     API_VENDOR = 'api.vendor'
     API_FORMAT = 'api.format'
 
-    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

@@ -4,34 +4,40 @@ module Grape
   module ErrorFormatter
     class Base
       class << self
-        def call(message, backtrace, options = {}, env = nil, original_exception = nil)
-          merge_backtrace = backtrace.present? && options.dig(:rescue_options, :backtrace)
-          merge_original_exception = original_exception && options.dig(:rescue_options, :original_exception)
-
-          wrapped_message = wrap_message(present(message, env))
+        # 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] = backtrace if merge_backtrace
-            wrapped_message[:original_exception] = original_exception.inspect if merge_original_exception
+            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
 
         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)
+          # 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
 
-          presenter = env[Grape::Env::API_ENDPOINT].entity_class_for_obj(presented_message, present_options)
+          presenter = with || env[Grape::Env::API_ENDPOINT].entity_class_for_obj(payload)
 
           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
@@ -39,25 +45,25 @@ module Grape
             presenter = found_code[2] if found_code
           end
 
-          if presenter
-            embeds = { env: env }
-            embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
-            presented_message = presenter.represent(presented_message, embeds).serializable_hash
-          end
+          return payload unless presenter
 
-          presented_message
+          embeds = { env: }
+          embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
+          presenter.represent(payload, embeds).serializable_hash
         end
 
         def wrap_message(message)
           return message if message.is_a?(Hash)
 
-          { message: message }
+          { message: }
         end
 
         def format_structured_message(_structured_message)
           raise NotImplementedError
         end
 
+        private
+
         def inherited(klass)
           super
           ErrorFormatter.register(klass)

data/lib/grape/error_formatter/json.rb

@@ -11,6 +11,12 @@ module Grape
         private
 
         def wrap_message(message)
+          # 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)
 

data/lib/grape/error_formatter/txt.rb

@@ -5,16 +5,16 @@ module Grape
     class Txt < Base
       def self.format_structured_message(structured_message)
         message = structured_message[:message] || Grape::Json.dump(structured_message)
-        Array.wrap(message).tap do |final_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
-        end.join("\r\n ")
+        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.rb

@@ -6,10 +6,14 @@ module Grape
 
     module_function
 
-    def formatter_for(format, error_formatters = nil, default_error_formatter = nil)
+    # 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)
 
-      registry[format] || default_error_formatter || Grape::ErrorFormatter::Txt
+      registry[format]
     end
   end
 end

data/lib/grape/exceptions/base.rb

@@ -3,9 +3,9 @@
 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
 
@@ -17,58 +17,34 @@ module Grape
       end
 
       def [](index)
-        send index
+        __send__ index
       end
 
-      protected
+      private
 
-      # 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)
+      def compose_message(key, **)
+        short_message = translate_message(key, **)
         return short_message unless short_message.is_a?(Hash)
 
-        each_steps(key, attributes).with_object(+'') do |detail_array, message|
-          message << "\n#{detail_array[0]}:\n  #{detail_array[1]}" unless detail_array[1].blank?
-        end
-      end
-
-      def each_steps(key, attributes)
-        return enum_for(:each_steps, key, attributes) unless block_given?
-
-        yield 'Problem', translate_message(:"#{key}.problem", attributes)
-        yield 'Summary', translate_message(:"#{key}.summary", attributes)
-        yield 'Resolution', translate_message(:"#{key}.resolution", attributes)
-      end
+        MESSAGE_STEPS.filter_map do |step, label|
+          next unless short_message.key?(step)
 
-      def translate_attributes(keys, options = {})
-        keys.map do |key|
-          translate("#{BASE_ATTRIBUTES_KEY}.#{key}", options.merge(default: key.to_s))
-        end.join(', ')
+          detail = translate_message(:"#{key}.#{step}", **)
+          "\n#{label}:\n  #{detail}" if detail.present?
+        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}", options.merge(default: ''))
+          translate(translation_key, **)
+        when Hash
+          translation_key => { key:, **opts }
+          translate(key, **opts)
         when Proc
-          key.call
-        else
-          key
-        end
-      end
-
-      def translate(key, options)
-        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', Grape.deprecator)

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

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class UnknownAuthStrategy < Base
       def initialize(strategy:)
-        super(message: compose_message(:unknown_auth_strategy, strategy: strategy))
+        super(message: compose_message(:unknown_auth_strategy, strategy:))
       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

@@ -4,7 +4,7 @@ module Grape
   module Exceptions
     class UnknownParamsBuilder < Base
       def initialize(params_builder_type)
-        super(message: compose_message(:unknown_params_builder, params_builder_type: params_builder_type))
+        super(message: compose_message(:unknown_params_builder, params_builder_type:))
       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', Grape.deprecator)

data/lib/grape/exceptions/validation.rb

@@ -3,16 +3,26 @@
 module Grape
   module Exceptions
     class Validation < Base
-      attr_accessor :params, :message_key
+      EMPTY_BACKTRACE = [].freeze
+
+      attr_reader :params, :message_key
 
       def initialize(params:, message: nil, status: nil, headers: nil)
-        @params = params
-        if message
-          @message_key = message if message.is_a?(Symbol)
-          message = translate_message(message)
-        end
+        @params = Array(params)
+        translated =
+          if message
+            @message_key = case message
+                           when Symbol then message
+                           when Hash then message[:key]
+                           end
+            translate_message(message)
+          end
 
-        super(status: status, message: message, headers: headers)
+        super(status:, message: translated, headers:)
+        # Pre-seed the backtrace so Ruby's raise skips capture. Validation errors are
+        # a hot path (raised per bad attribute) and end up as 400 Bad Request responses;
+        # backtraces here point into Grape internals and have no diagnostic value.
+        set_backtrace(EMPTY_BACKTRACE)
       end
 
       # Remove all the unnecessary stuff from Grape::Exceptions::Base like status
@@ -20,6 +30,14 @@ module Grape
       def as_json(*_args)
         to_s
       end
+
+      # Returns +self+ so callers (e.g. +ValidationErrors#initialize+) can treat
+      # a single +Validation+ and a +ValidationArrayErrors+ wrapper uniformly via
+      # +flat_map(&:errors)+ — Array returns flatten in, non-Array returns
+      # (i.e. this +self+) append as one element.
+      def errors
+        self
+      end
     end
   end
 end

data/lib/grape/exceptions/validation_array_errors.rb

@@ -3,11 +3,15 @@
 module Grape
   module Exceptions
     class ValidationArrayErrors < Base
+      EMPTY_BACKTRACE = [].freeze
+
       attr_reader :errors
 
       def initialize(errors)
         super()
         @errors = errors
+        # Skip backtrace capture — see Grape::Exceptions::Validation for rationale.
+        set_backtrace(EMPTY_BACKTRACE)
       end
     end
   end

data/lib/grape/exceptions/validation_errors.rb

@@ -3,24 +3,11 @@
 module Grape
   module Exceptions
     class ValidationErrors < Base
-      ERRORS_FORMAT_KEY = 'grape.errors.format'
-      DEFAULT_ERRORS_FORMAT = '%<attributes>s %<message>s'
-
-      include Enumerable
-
       attr_reader :errors
 
-      def initialize(errors: [], headers: {})
-        @errors = errors.group_by(&:params)
-        super(message: full_messages.join(', '), status: 400, headers: headers)
-      end
-
-      def each
-        errors.each_pair do |attribute, errors|
-          errors.each do |error|
-            yield attribute, error
-          end
-        end
+      def initialize(exceptions: [], headers: {})
+        @errors = exceptions.flat_map(&:errors).group_by(&:params)
+        super(message: full_messages.join(', '), status: 400, headers:)
       end
 
       def as_json(**_opts)
@@ -37,17 +24,28 @@ module Grape
       end
 
       def full_messages
-        messages = map do |attributes, error|
-          I18n.t(
-            ERRORS_FORMAT_KEY,
-            default: DEFAULT_ERRORS_FORMAT,
-            attributes: translate_attributes(attributes),
-            message: error.message
-          )
+        messages = errors.flat_map do |attributes, errs|
+          errs.map do |error|
+            translate(
+              :format,
+              scope: 'grape.errors',
+              default: '%<attributes>s %<message>s',
+              attributes: translate_attributes(attributes),
+              message: error.message
+            )
+          end
         end
         messages.uniq!
         messages
       end
+
+      private
+
+      def translate_attributes(keys)
+        keys.map do |key|
+          translate(key, scope: 'grape.errors.attributes', default: key.to_s)
+        end.join(', ')
+      end
     end
   end
 end

data/lib/grape/formatter/json.rb

@@ -4,6 +4,7 @@ module Grape
   module Formatter
     class Json < Base
       def self.call(object, _env)
+        return object.to_s if object.is_a?(Grape::PrecompiledJson)
         return object.to_json if object.respond_to?(:to_json)
 
         ::Grape::Json.dump(object)

data/lib/grape/formatter/serializable_hash.rb

@@ -5,6 +5,7 @@ module Grape
     class SerializableHash < Base
       class << self
         def call(object, _env)
+          return object.to_s if object.is_a?(Grape::PrecompiledJson)
           return object if object.is_a?(String)
           return ::Grape::Json.dump(serialize(object)) if serializable?(object)
           return object.to_json if object.respond_to?(:to_json)
@@ -19,15 +20,11 @@ module Grape
         end
 
         def serialize(object)
-          if object.respond_to? :serializable_hash
-            object.serializable_hash
-          elsif array_serializable?(object)
-            object.map(&:serializable_hash)
-          elsif object.is_a?(Hash)
-            object.transform_values { |v| serialize(v) }
-          else
-            object
-          end
+          return object.serializable_hash if object.respond_to?(:serializable_hash)
+          return object.map(&:serializable_hash) if array_serializable?(object)
+          return object.transform_values { |v| serialize(v) } if object.is_a?(Hash)
+
+          object
         end
 
         def array_serializable?(object)