grape 1.8.0 → 4.0.1

data/lib/grape/middleware/base.rb

@@ -1,30 +1,30 @@
 # frozen_string_literal: true
 
-require 'grape/dsl/headers'
-
 module Grape
   module Middleware
     class Base
-      include Helpers
-
-      attr_reader :app, :env, :options
-
-      TEXT_HTML = 'text/html'
-
       include Grape::DSL::Headers
 
+      attr_reader :app, :env, :options, :config
+
       # @param [Rack Application] app The standard argument for a Rack middleware.
-      # @param [Hash] options A hash of options, simply stored for use by subclasses.
-      def initialize(app, *options)
+      # @param [Hash] options Options forwarded to the subclass. When the
+      #   subclass declares an `Options` Data class, the kwargs are routed
+      #   through it and exposed via {#config}; {#options} keeps returning a
+      #   frozen Hash representation for back-compat with subclasses that read
+      #   `options[:key]`. Otherwise the kwargs are deep-merged with the
+      #   subclass's `DEFAULT_OPTIONS` Hash (legacy path) and frozen.
+      def initialize(app, **options)
         @app = app
-        @options = options.any? ? default_options.merge(options.shift) : default_options
+        if (config_class = options_data_class)
+          @config = config_class.new(**options)
+          @options = @config.to_h.freeze
+        else
+          @options = merge_default_options(options).freeze
+        end
         @app_response = nil
       end
 
-      def default_options
-        {}
-      end
-
       def call(env)
         dup.call!(env).to_a
       end
@@ -57,40 +57,63 @@ module Grape
       # @return [Response, nil] a Rack SPEC response or nil to call the application afterwards.
       def after; end
 
-      def response
-        return @app_response if @app_response.is_a?(Rack::Response)
-
-        @app_response = Rack::Response.new(@app_response[2], @app_response[0], @app_response[1])
+      def rack_request
+        @rack_request ||= Rack::Request.new(env)
       end
 
-      def content_type_for(format)
-        HashWithIndifferentAccess.new(content_types)[format]
+      def context
+        env[Grape::Env::API_ENDPOINT]
       end
 
-      def content_types
-        ContentTypes.content_types_for(options[:content_types])
-      end
+      def response
+        return @app_response if @app_response.is_a?(Rack::Response)
 
-      def content_type
-        content_type_for(env[Grape::Env::API_FORMAT] || options[:format]) || TEXT_HTML
+        @app_response = Rack::Response[*@app_response]
       end
 
-      def mime_types
-        @mime_type ||= content_types.each_pair.with_object({}) do |(k, v), types_without_params|
-          types_without_params[v.split(';').first] = k
-        end
+      def query_params
+        rack_request.GET
+      rescue *Grape::RACK_ERRORS
+        raise Grape::Exceptions::RequestError
       end
 
       private
 
       def merge_headers(response)
-        return unless headers.is_a?(Hash)
+        return if @header.blank?
 
         case response
-        when Rack::Response then response.headers.merge!(headers)
-        when Array          then response[1].merge!(headers)
+        when Rack::Response then response.headers.merge!(@header)
+        when Array          then response[1].merge!(@header)
         end
       end
+
+      def merge_default_options(options)
+        return default_options.deep_merge(options) if respond_to?(:default_options)
+
+        default_options_constant&.deep_merge(options) || options
+      end
+
+      # self.class::Options honours middleware inheritance (e.g. Versioner::Path
+      # → Versioner::Base) and, unlike const_defined?, never resolves a
+      # top-level ::Options on Object. Absent an own/inherited Options class,
+      # the lookup raises NameError and we fall back to the legacy path.
+      def options_data_class
+        self.class::Options
+      rescue NameError
+        nil
+      end
+
+      # Same idea as {#options_data_class} for the legacy DEFAULT_OPTIONS Hash.
+      def default_options_constant
+        self.class::DEFAULT_OPTIONS
+      rescue NameError
+        nil
+      end
+
+      def try_scrub(obj)
+        obj.respond_to?(:valid_encoding?) && !obj.valid_encoding? ? obj.scrub : obj
+      end
     end
   end
 end

data/lib/grape/middleware/error.rb

@@ -1,138 +1,337 @@
 # frozen_string_literal: true
 
-require 'grape/middleware/base'
-require 'active_support/core_ext/string/output_safety'
-
 module Grape
   module Middleware
     class Error < Base
-      def default_options
-        {
-          default_status: 500, # default status returned on error
-          default_message: '',
-          format: :txt,
-          helpers: nil,
-          formatters: {},
-          error_formatters: {},
-          rescue_all: false, # true to rescue all exceptions
-          rescue_grape_exceptions: false,
-          rescue_subclasses: true, # rescue subclasses of exceptions listed
-          rescue_options: {
-            backtrace: false, # true to display backtrace, true to let Grape handle Grape::Exceptions
-            original_exception: false # true to display exception
-          },
-          rescue_handlers: {}, # rescue handler blocks
-          base_only_rescue_handlers: {}, # rescue handler blocks rescuing only the base class
-          all_rescue_handler: nil # rescue handler block to rescue from all exceptions
-        }
-      end
-
-      def initialize(app, *options)
-        super
-        self.class.send(:include, @options[:helpers]) if @options[:helpers]
+      extend Forwardable
+      include PrecomputedContentTypes
+
+      Options = Data.define(
+        :all_rescue_handler, :base_only_rescue_handlers, :content_types,
+        :default_error_formatter, :default_message, :default_status,
+        :error_formatters, :format,
+        :grape_exceptions_rescue_handler, :internal_grape_exceptions_rescue_handler,
+        :rescue_all, :rescue_grape_exceptions, :rescue_handlers, :rescue_options
+      ) do
+        def initialize(
+          all_rescue_handler: nil, base_only_rescue_handlers: nil, content_types: nil,
+          default_error_formatter: nil, default_message: '', default_status: 500,
+          error_formatters: nil, format: :txt,
+          grape_exceptions_rescue_handler: nil, internal_grape_exceptions_rescue_handler: nil,
+          rescue_all: false, rescue_grape_exceptions: false, rescue_handlers: nil,
+          rescue_options: nil
+        )
+          # `rescue_options:` and `default_error_formatter:` arrive nil from
+          # `Endpoint#error_middleware_options` when the API called no
+          # `rescue_from` and no `format` — and an explicit nil bypasses the
+          # keyword defaults above, so restore them here rather than letting nil
+          # propagate to `def_delegator :rescue_options, :backtrace` or to the
+          # formatter lookup in `#format_message`.
+          super(
+            rescue_options: rescue_options || Grape::DSL::RescueOptions.new,
+            default_error_formatter: default_error_formatter || Grape::ErrorFormatter::Txt,
+            all_rescue_handler:, base_only_rescue_handlers:, content_types:,
+            default_message:, default_status:, error_formatters:, format:,
+            grape_exceptions_rescue_handler:, internal_grape_exceptions_rescue_handler:,
+            rescue_all:, rescue_grape_exceptions:, rescue_handlers:
+          )
+        end
       end
 
+      def_delegators :config,
+                     :all_rescue_handler, :base_only_rescue_handlers, :default_error_formatter,
+                     :default_message, :default_status, :error_formatters, :format,
+                     :grape_exceptions_rescue_handler, :internal_grape_exceptions_rescue_handler,
+                     :rescue_all, :rescue_grape_exceptions, :rescue_handlers, :rescue_options
+
+      # +:backtrace+ / +:original_exception+ on the rescue options become
+      # +#include_backtrace+ / +#include_original_exception+ on the middleware,
+      # which is what the formatter call site reads.
+      def_delegator :rescue_options, :backtrace, :include_backtrace
+      def_delegator :rescue_options, :original_exception, :include_original_exception
+
+      # Emitted by {#render_failsafe_response} once even the framework's own message
+      # could not be rendered. Deliberately built without a formatter, an i18n
+      # lookup or anything else that could be the thing that is broken.
+      FAILSAFE_STATUS = 500
+      FAILSAFE_MESSAGE = '500 Internal Server Error'
+      FAILSAFE_CONTENT_TYPE = 'text/plain'
+
       def call!(env)
         @env = env
-        begin
-          error_response(catch(:error) do
-            return @app.call(@env)
-          end)
-        rescue Exception => e # rubocop:disable Lint/RescueException
-          handler =
-            rescue_handler_for_base_only_class(e.class) ||
-            rescue_handler_for_class_or_its_ancestor(e.class) ||
-            rescue_handler_for_grape_exception(e.class) ||
-            rescue_handler_for_any_class(e.class) ||
-            raise
-
-          run_rescue_handler(handler, e)
-        end
+        error_response(catch(:error) { return @app.call(@env) })
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        run_rescue_handler(find_handler(e.class), e, @env[Grape::Env::API_ENDPOINT])
       end
 
-      def error!(message, status = options[:default_status], headers = {}, backtrace = [], original_exception = nil)
-        headers = headers.reverse_merge(Grape::Http::Headers::CONTENT_TYPE => content_type)
-        rack_response(format_message(message, backtrace, original_exception), status, headers)
+      private
+
+      def rack_response(status, headers, message)
+        body = html_content_type?(headers[Rack::CONTENT_TYPE]) ? Rack::Utils.escape_html(message) : message
+        Rack::Response.new(Array.wrap(body), Rack::Utils.status_code(status), Grape::Util::Header.new.merge!(headers))
       end
 
-      def default_rescue_handler(e)
-        error_response(message: e.message, backtrace: e.backtrace, original_exception: e)
+      # Escaping must key off the media type only, case-insensitively. Comparing
+      # the raw header against 'text/html' would let a parameterized value such
+      # as 'text/html; charset=utf-8' (or a differently-cased 'Text/HTML', which
+      # browsers still treat as HTML) skip escaping and reflect an unescaped
+      # message into an HTML response. Such a header can be set from several
+      # places (a registered content type, or a custom Content-Type passed to
+      # error!/rescue_from), but they all render here.
+      def html_content_type?(content_type)
+        Grape::ContentTypes.media_type(content_type).to_s.casecmp?('text/html')
       end
 
-      # TODO: This method is deprecated. Refactor out.
-      def error_response(error = {})
-        status = error[:status] || options[:default_status]
-        message = error[:message] || options[:default_message]
-        headers = { Grape::Http::Headers::CONTENT_TYPE => content_type }
-        headers.merge!(error[:headers]) if error[:headers].is_a?(Hash)
-        backtrace = error[:backtrace] || error[:original_exception]&.backtrace || []
-        original_exception = error.is_a?(Exception) ? error : error[:original_exception] || nil
-        rack_response(format_message(message, backtrace, original_exception), status, headers)
+      # The registry answers nil for a format nothing is registered for, and
+      # the API's +default_error_formatter+ — +ErrorFormatter::Txt+ unless the
+      # API set another — takes it from there, so this always has something
+      # callable. The +throw :error, 406+ that used to stand in for a missing
+      # formatter could not work anyway: nothing catches +:error+ around this
+      # call (+#call!+ has left its +catch+ by the time +error_response+ runs),
+      # so it raised +UncaughtThrowError+ and the request answered with the
+      # failsafe 500 rather than the 406 it named.
+      def format_message(error)
+        current_format = env[Grape::Env::API_FORMAT] || format
+        formatter = Grape::ErrorFormatter.formatter_for(current_format, error_formatters) || default_error_formatter
+        formatter.call(error:, env:, include_backtrace:, include_original_exception:)
       end
 
-      def rack_response(message, status = options[:default_status], headers = { Grape::Http::Headers::CONTENT_TYPE => content_type })
-        message = ERB::Util.html_escape(message) if headers[Grape::Http::Headers::CONTENT_TYPE] == TEXT_HTML
-        Rack::Response.new([message], Rack::Utils.status_code(status), headers)
+      def find_handler(klass)
+        registered_entry = registered_rescue_handler_entry(klass)
+
+        grape_exceptions_precedence_handler(klass, registered_entry) ||
+          registered_entry&.last ||
+          rescue_handler_for_grape_exception(klass) ||
+          rescue_handler_for_any_class(klass) ||
+          raise
       end
 
-      def format_message(message, backtrace, original_exception = nil)
-        format = env[Grape::Env::API_FORMAT] || options[:format]
-        formatter = Grape::ErrorFormatter.formatter_for(format, **options)
-        throw :error,
-              status: 406,
-              message: "The requested format '#{format}' is not supported.",
-              backtrace: backtrace,
-              original_exception: original_exception unless formatter
-        formatter.call(message, backtrace, options, env, original_exception)
+      def error_response(error = nil)
+        raw = Grape::Exceptions::ErrorResponse.coerce(error)
+        headers = { Rack::CONTENT_TYPE => content_type }
+        headers.merge!(raw.headers) if raw.headers.is_a?(Hash)
+        payload = raw.with(
+          status: raw.status || default_status,
+          message: raw.message || default_message,
+          headers:,
+          backtrace: resolved_backtrace(raw)
+        )
+        env[Grape::Env::API_ENDPOINT].status(payload.status) # error! may not have been called
+        render_response(payload)
       end
 
-      private
+      # The backtrace an error formatter is handed. Assembled only when the API
+      # asked for one with `rescue_from ..., backtrace: true`: reading it off
+      # the exception is not free — +Exception#backtrace+ builds the whole Array
+      # of location strings — and every built-in formatter drops it otherwise.
+      # A formatter that wants one regardless still has +original_exception+.
+      def resolved_backtrace(raw)
+        return [] unless include_backtrace
+
+        raw.backtrace || raw.original_exception&.backtrace || []
+      end
 
-      def rescue_handler_for_base_only_class(klass)
-        error, handler = options[:base_only_rescue_handlers].find { |err, _handler| klass == err }
+      # Rendering runs inside #call!'s own rescue clause, so it is not covered by
+      # that rescue: an error formatter that raises on the payload it was handed
+      # takes the exception out through every middleware above Grape. By this
+      # point Grape has committed to answering with an error, so it answers with
+      # one that does not depend on the payload rather than dropping the request.
+      #
+      # +Grape.config.raise_rendering_errors+ opts back out, for an application
+      # that would rather have the exception propagate as it did before.
+      def render_response(payload)
+        rack_response(payload.status, payload.headers, format_message(payload))
+      rescue StandardError => e
+        raise if Grape.config.raise_rendering_errors
 
-        return unless error
+        record_rendering_failure(e)
+        render_failsafe_response
+      end
+
+      # The exception is published on the rack env (see {#expose_exception}) and
+      # written to +rack.errors+ so it reaches the log with no tracker installed.
+      # Rails writes to $stderr from its failsafe branch for the same reason:
+      # deferring the logging to the application is not an option when the
+      # application's own error rendering is what broke.
+      def record_rendering_failure(error)
+        expose_exception(error)
+        env[Rack::RACK_ERRORS]&.write("Grape could not render the error response: #{error.class}: #{error.message}\n")
+      end
+
+      # First retry the API's own format with the framework's InternalServerError,
+      # whose message is a static string and so cannot be what defeated the first
+      # attempt. Should even that fail — a wholesale broken formatter, rather than
+      # one payload it choked on — drop the formatter entirely. Both attempts call
+      # {#format_message} directly rather than re-entering {#error_response}, so
+      # this path cannot recurse.
+      def render_failsafe_response
+        headers = { Rack::CONTENT_TYPE => content_type }
+        rack_response(FAILSAFE_STATUS, headers, format_message(failsafe_payload(headers)))
+      rescue StandardError
+        rack_response(FAILSAFE_STATUS, { Rack::CONTENT_TYPE => FAILSAFE_CONTENT_TYPE }, FAILSAFE_MESSAGE)
+      end
+
+      # Publish an exception Grape swallowed, on both keys. +grape.exception+ is
+      # Grape's own and has been set on these paths all along; +rack.exception+ is
+      # what the ecosystem actually reads to find an exception that never
+      # propagated — sentry-ruby collects +env['rack.exception'] ||
+      # env['sinatra.error']+ — so a tracker mounted above Grape keeps reporting
+      # these with no application change.
+      def expose_exception(error)
+        env[Grape::Env::GRAPE_EXCEPTION] = error
+        env[Grape::Env::RACK_EXCEPTION] = error
+      end
+
+      def failsafe_payload(headers)
+        Grape::Exceptions::ErrorResponse.new(
+          status: FAILSAFE_STATUS,
+          message: Grape::Exceptions::InternalServerError.new.message,
+          headers:,
+          backtrace: [],
+          original_exception: nil
+        )
+      end
+
+      def default_rescue_handler(exception)
+        error_response(
+          Grape::Exceptions::ErrorResponse.new(
+            message: exception.message,
+            backtrace: exception.backtrace,
+            original_exception: exception
+          )
+        )
+      end
+
+      def registered_rescue_handler(klass)
+        registered_rescue_handler_entry(klass)&.last
+      end
 
-        handler || :default_rescue_handler
+      # The matched entry rather than just its handler, so callers can tell
+      # *which* class matched — see {#grape_exceptions_precedence_handler}.
+      # @return [Array(Class, #call), nil]
+      def registered_rescue_handler_entry(klass)
+        rescue_handler_entry_from(base_only_rescue_handlers) { |err| klass == err } ||
+          rescue_handler_entry_from(rescue_handlers) { |err| klass <= err }
       end
 
-      def rescue_handler_for_class_or_its_ancestor(klass)
-        error, handler = options[:rescue_handlers].find { |err, _handler| klass <= err }
+      def rescue_handler_entry_from(handlers)
+        error, handler = handlers&.find { |err, _handler| yield(err) }
 
         return unless error
 
-        handler || :default_rescue_handler
+        [error, handler || method(:default_rescue_handler)]
+      end
+
+      # +rescue_from :grape_exceptions+ is an opt-in to keep Grape's own errors
+      # rendering with their own status — a validation failure stays a 400
+      # instead of becoming whatever the app's catch-all returns.
+      #
+      # It only ever worked against +rescue_from :all+, which lives in
+      # +all_rescue_handler+ and is consulted last. Spelled as a class instead,
+      # +rescue_from StandardError+ is a *registered* handler, matched first,
+      # and Grape's exceptions are StandardErrors — so the opt-in silently did
+      # nothing and validation errors came back as 500s either way.
+      #
+      # Let it win over a handler that only matched through a non-Grape
+      # ancestor. One registered for a Grape exception class is more specific
+      # than the opt-in and still wins, so an explicit
+      # +rescue_from Grape::Exceptions::ValidationErrors+ keeps its handler.
+      #
+      # InvalidVersionHeader is left alone: it must keep reaching Rack so the
+      # next versioned route is tried.
+      def grape_exceptions_precedence_handler(klass, registered_entry)
+        return unless rescue_grape_exceptions
+        return unless klass <= Grape::Exceptions::Base
+        return if klass == Grape::Exceptions::InvalidVersionHeader
+
+        matched, = registered_entry
+        return if matched.nil? || matched <= Grape::Exceptions::Base
+
+        grape_exceptions_rescue_handler || method(:error_response)
       end
 
       def rescue_handler_for_grape_exception(klass)
         return unless klass <= Grape::Exceptions::Base
-        return :error_response if klass == Grape::Exceptions::InvalidVersionHeader
-        return unless options[:rescue_grape_exceptions] || !options[:rescue_all]
+        return method(:error_response) if klass == Grape::Exceptions::InvalidVersionHeader
+        return unless rescue_grape_exceptions || !rescue_all
 
-        options[:grape_exceptions_rescue_handler] || :error_response
+        grape_exceptions_rescue_handler || method(:error_response)
       end
 
       def rescue_handler_for_any_class(klass)
         return unless klass <= StandardError
-        return unless options[:rescue_all] || options[:rescue_grape_exceptions]
+        return unless rescue_all || rescue_grape_exceptions
 
-        options[:all_rescue_handler] || :default_rescue_handler
+        all_rescue_handler || method(:default_rescue_handler)
       end
 
-      def run_rescue_handler(handler, error)
-        if handler.instance_of?(Symbol)
-          raise NoMethodError, "undefined method '#{handler}'" unless respond_to?(handler)
-
-          handler = public_method(handler)
+      def run_rescue_handler(handler, error, endpoint, redispatched: false)
+        callable = handler.is_a?(Symbol) ? endpoint.public_method(handler) : handler
+        response = catch(:error) do
+          callable.arity.zero? ? endpoint.instance_exec(&callable) : endpoint.instance_exec(error, &callable)
+        rescue StandardError => e
+          return redispatch(e, endpoint, redispatched)
         end
 
-        response = handler.arity.zero? ? instance_exec(&handler) : instance_exec(error, &handler)
+        return error_response(response) if error?(response)
+        return response if response.is_a?(Rack::Response)
 
-        if response.is_a?(Rack::Response)
-          response
-        else
-          run_rescue_handler(:default_rescue_handler, Grape::Exceptions::InvalidResponse.new)
-        end
+        run_rescue_handler(method(:default_rescue_handler), Grape::Exceptions::InvalidResponse.new, endpoint)
+      end
+
+      # Route an exception raised inside a +rescue_from+ block.
+      #
+      # * If we have already redispatched once (the redispatched handler
+      #   itself raised), go straight to {#framework_default} — bounds the
+      #   chain at one redispatch.
+      # * Else if the exception has a registered +rescue_from+ handler,
+      #   run it.
+      # * Else if it's a +Grape::Exceptions::Base+ subclass, render it
+      #   through +error_response+ with its own +status+ and +message+.
+      # * Else fall through to {#safe_default}, which lets the user opt
+      #   in via +rescue_from :internal_grape_exceptions+ or, failing
+      #   that, applies the framework default.
+      def redispatch(error, endpoint, already_redispatched)
+        return framework_default(endpoint) if already_redispatched
+
+        registered = registered_rescue_handler(error.class)
+
+        return run_rescue_handler(registered, error, endpoint, redispatched: true) if registered
+        return run_rescue_handler(method(:error_response), error, endpoint, redispatched: true) if error.is_a?(Grape::Exceptions::Base)
+
+        safe_default(error, endpoint)
+      end
+
+      # The unrecognised-error path. Exposes the original exception on
+      # the rack env so upstream Rack middleware (loggers, error
+      # trackers) can observe it. If the user registered a
+      # +rescue_from :internal_grape_exceptions+ handler, that handler
+      # runs and owns the response. Otherwise the framework renders the
+      # generic +InternalServerError+ — never the original exception's
+      # message. The framework deliberately does no logging of its own
+      # here; that's the application's call.
+      def safe_default(error, endpoint)
+        expose_exception(error)
+        return run_rescue_handler(internal_grape_exceptions_rescue_handler, error, endpoint, redispatched: true) if internal_grape_exceptions_rescue_handler
+
+        framework_default(endpoint)
+      end
+
+      def framework_default(endpoint)
+        run_rescue_handler(method(:default_rescue_handler), Grape::Exceptions::InternalServerError.new, endpoint)
+      end
+
+      def error!(message, status = default_status, headers = {}, backtrace = [], original_exception = nil)
+        env[Grape::Env::API_ENDPOINT].status(status) # not error! inside route
+        merged_headers = { Rack::CONTENT_TYPE => content_type }.merge!(headers)
+        error = Grape::Exceptions::ErrorResponse.new(
+          status:, message:, headers: merged_headers, backtrace:, original_exception:
+        )
+        rack_response(status, merged_headers, format_message(error))
+      end
+
+      def error?(response)
+        response.is_a?(Grape::Exceptions::ErrorResponse)
       end
     end
   end