grape 4.0.1 → 4.1.0

data/lib/grape/error_formatter/base.rb

@@ -32,19 +32,7 @@ module Grape
             with = payload.delete(:with)
           end
 
-          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
-
-            presenter = found_code[2] if found_code
-          end
-
+          presenter = with || env[Grape::Env::API_ENDPOINT].entity_class_for_obj(payload) || failure_presenter(payload, env)
           return payload unless presenter
 
           embeds = { env: }
@@ -64,6 +52,33 @@ module Grape
 
         private
 
+        # The entity the route's failure codes name for the status being
+        # answered: those entities document a structured error body.
+        #
+        # A String message has no attributes for one to expose -- presenting
+        # it raised, and the failsafe answered 500 in place of the status
+        # +error!+ asked for -- so it is left for #wrap_message. And a route's
+        # failure presenters are written for the errors the endpoint itself
+        # raises: one raised by middleware before the endpoint ran -- it has
+        # no request yet -- keeps the shape that middleware gave it rather than
+        # being fit to an entity it was not written for.
+        def failure_presenter(payload, env)
+          return if payload.is_a?(String)
+
+          routing_args = env[Grape::Env::GRAPE_ROUTING_ARGS]
+          endpoint = env[Grape::Env::API_ENDPOINT]
+          return if routing_args.nil? || !endpoint.request
+
+          presenter_for_status(routing_args[:route_info].failure, endpoint.status)
+        end
+
+        # The entity +failure+ names for +status+, among the +[code, message,
+        # entity]+ entries a route's failure codes are.
+        def presenter_for_status(failure, status)
+          found_code = Array(failure).find { |http_code| http_code[0].to_i == status && http_code[2].respond_to?(:represent) }
+          found_code[2] if found_code
+        end
+
         def inherited(klass)
           super
           ErrorFormatter.register(klass)

data/lib/grape/error_formatter/json.rb

@@ -23,8 +23,11 @@ module Grape
           { error: ensure_utf8(message) }
         end
 
+        # Re-encoding a String that already is valid UTF-8 only copies it, for
+        # about 260 ns on every error response.
         def ensure_utf8(message)
           return message unless message.respond_to? :encode
+          return message if message.is_a?(String) && message.encoding == Encoding::UTF_8 && message.valid_encoding?
 
           message.encode('UTF-8', invalid: :replace, undef: :replace)
         end

data/lib/grape/error_formatter/jsonl.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Grape
+  module ErrorFormatter
+    # An error renders as the JSON error formatter renders it, ended by a
+    # newline, so the body is a JSON Lines document of one line.
+    class Jsonl < Json
+      class << self
+        def format_structured_message(structured_message)
+          "#{super}\n"
+        end
+      end
+    end
+  end
+end

data/lib/grape/error_formatter/xml.rb

@@ -3,8 +3,10 @@
 module Grape
   module ErrorFormatter
     class Xml < Base
+      # Base#wrap_message always hands over a Hash, which ActiveSupport's
+      # conversions (required by grape.rb) give +to_xml+.
       def self.format_structured_message(structured_message)
-        structured_message.respond_to?(:to_xml) ? structured_message.to_xml(root: :error) : structured_message.to_s
+        structured_message.to_xml(root: :error)
       end
     end
   end

data/lib/grape/exceptions/error_response.rb

@@ -2,13 +2,29 @@
 
 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
+    # The frozen payload thrown via `throw :error, ...` (or raised by `error!`
+    # inside a `Grape::Exceptions::Halt`) and consumed by
+    # `Middleware::Error#error_response`. Replaces the implicit-schema Hash
+    # that previously circulated between throw sites and the error middleware.
+    #
+    # A plain frozen class rather than a +Data+: every error response builds
+    # at least two (the payload, then the one +error_response+ fills the
+    # defaults into), and +Data+'s constructor takes its keywords as a Hash it
+    # then validates, about 450 ns apiece. A Ruby method keeps keyword
+    # arguments on the stack. It answers only what is read off it: its
+    # readers.
+    class ErrorResponse
+      MEMBERS = %i[status message headers backtrace original_exception].freeze
+
+      attr_reader(*MEMBERS)
+
       def initialize(status: nil, message: nil, headers: nil, backtrace: nil, original_exception: nil)
-        super
+        @status = status
+        @message = message
+        @headers = headers
+        @backtrace = backtrace
+        @original_exception = original_exception
+        freeze
       end
 
       def to_s
@@ -38,7 +54,7 @@ module Grape
         when Grape::Exceptions::Base
           from_exception(input)
         when Hash
-          new(**input.slice(:status, :message, :headers, :backtrace, :original_exception))
+          new(**input.slice(*MEMBERS))
         else
           new
         end

data/lib/grape/exceptions/halt.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    # Raised by +error!+ to end the request with an error response. It carries
+    # the ErrorResponse a +throw :error+ carries, and +Middleware::Error+
+    # renders it the same way: as it is, without consulting +rescue_from+.
+    #
+    # It is raised rather than thrown so that it leaves a block the way an
+    # exception does. Active Record rolls a transaction back only when an
+    # exception leaves its block, and commits it on a +throw+. A +throw+ cannot
+    # leave the fiber or thread it was thrown in either, while +Async::Task#wait+
+    # and +Thread#value+ re-raise an exception in the request's own.
+    #
+    # A StandardError on purpose: async treats any other exception leaving a
+    # task as fatal and stops its reactor. It is not a Grape::Exceptions::Base,
+    # so a +rescue+ of those around +error!+ still lets it through.
+    class Halt < StandardError
+      extend Forwardable
+
+      EMPTY_BACKTRACE = [].freeze
+
+      attr_reader :response
+
+      def_delegators :response, :status, :headers
+
+      # Keywords spelled out rather than forwarded with **, which would gather
+      # them into a Hash on every error! only to spread it again.
+      def initialize(status: nil, message: nil, headers: nil, backtrace: nil, original_exception: nil)
+        @response = ErrorResponse.new(status:, message:, headers:, backtrace:, original_exception:)
+        super(message)
+        # Pre-seed the backtrace so Ruby's raise skips capture, as
+        # Grape::Exceptions::Validation does: +error!+ is how a route answers
+        # with an error, and the backtrace would only point at that route.
+        set_backtrace(EMPTY_BACKTRACE)
+      end
+    end
+  end
+end

data/lib/grape/exceptions/validation.rb

@@ -9,16 +9,16 @@ module Grape
 
       def initialize(params:, message: nil, status: nil, headers: nil)
         @params = Array(params)
-        translated =
-          if message
-            @message_key = case message
-                           when Symbol then message
-                           when Hash then message[:key]
-                           end
-            translate_message(message)
-          end
+        # Without a message, StandardError#message answers with this class's
+        # name, and that reached the response -- from a custom validator with
+        # no default_message_key, say.
+        message ||= :invalid
+        @message_key = case message
+                       when Symbol then message
+                       when Hash then message[:key]
+                       end
 
-        super(status:, message: translated, headers:)
+        super(status:, message: translate_message(message), 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.

data/lib/grape/exceptions/validation_errors.rb

@@ -23,7 +23,19 @@ module Grape
         as_json.to_json
       end
 
+      # Translated once, when the error is built for its #message, and handed
+      # out as a copy from then on. Every lookup here is an I18n call of a few
+      # microseconds, and the README's recipe for answering with the list,
+      # +error!({ messages: e.full_messages }, 400)+, asked for all of them a
+      # second time. It also keeps the list the same as #message, which was
+      # already fixed at that point, if the locale changes in between.
       def full_messages
+        (@full_messages ||= translate_full_messages).dup
+      end
+
+      private
+
+      def translate_full_messages
         messages = errors.flat_map do |attributes, errs|
           errs.map do |error|
             translate(
@@ -39,8 +51,6 @@ module Grape
         messages
       end
 
-      private
-
       def translate_attributes(keys)
         keys.map do |key|
           translate(key, scope: 'grape.errors.attributes', default: key.to_s)

data/lib/grape/formatter/jsonl.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Grape
+  module Formatter
+    # Renders JSON Lines (https://jsonlines.org): one JSON value per line, each
+    # line ended by a newline. An Array renders one line per element, and any
+    # other object one line. A String is served as it is, taken to be JSON
+    # Lines already.
+    #
+    # An Enumerator renders as it is read rather than up front, so the server
+    # streams each line as the enumerator yields its element:
+    #
+    #   get :export do
+    #     User.find_each # without a block, an Enumerator
+    #   end
+    class Jsonl < Base
+      class << self
+        def call(object, env)
+          return object if object.is_a?(String)
+          return Grape::ServeStream::StreamResponse.new(object.lazy.map { |element| line(element, env) }) if object.is_a?(Enumerator)
+          return object.to_ary.map { |element| line(element, env) }.join if object.respond_to?(:to_ary)
+
+          line(object, env)
+        end
+
+        private
+
+        def line(object, env)
+          "#{Formatter::Json.call(object, env)}\n"
+        end
+      end
+    end
+  end
+end

data/lib/grape/formatter/markdown.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Grape
+  module Formatter
+    class Markdown < Base
+      # Md inherits this, so the format named in the error comes from the class
+      # name, the way Grape::Util::Registry derives the name each class is
+      # registered under.
+      def self.call(object, _env)
+        return object.to_markdown if object.respond_to?(:to_markdown)
+        return object if object.is_a?(String)
+
+        raise Grape::Exceptions::InvalidFormatter.new(object.class, name.demodulize.underscore)
+      end
+    end
+  end
+end

data/lib/grape/formatter/md.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Formatter
+    # Registers Markdown's rendering under +md+ too, for an API that declares
+    # +content_type :md+ rather than +:markdown+ (see
+    # Grape::ContentTypes::FORMAT_SYNONYMS).
+    class Md < Markdown
+    end
+  end
+end

data/lib/grape/locale/en.yml

@@ -12,6 +12,7 @@ en:
         except_values: 'has a value not allowed'
         incompatible_option_values: '%{option1}: %{value1} is incompatible with %{option2}: %{value2}'
         internal_server_error: 'Internal Server Error'
+        invalid: 'is invalid'
         invalid_accept_header:
           problem: 'invalid accept header'
           resolution: '%{message}'

data/lib/grape/middleware/auth/base.rb

@@ -12,10 +12,25 @@ module Grape
           raise Grape::Exceptions::UnknownAuthStrategy.new(strategy: options[:type]) unless @auth_strategy
         end
 
+        # Base#call copies the middleware per request so #call! can keep the
+        # env in an ivar, and all that reads it is the strategy's block, to find
+        # the endpoint that checks the credentials. The block takes the
+        # endpoint from the env it was built for instead, so the request is
+        # answered by the one instance the stack built.
+        def call(env)
+          authenticate(env).to_a
+        end
+
         def call!(env)
           @env = env
+          authenticate(env)
+        end
+
+        private
+
+        def authenticate(env)
           @auth_strategy.create(app, options) do |*args|
-            context.instance_exec(*args, &options[:proc])
+            env[Grape::Env::API_ENDPOINT].instance_exec(*args, &options[:proc])
           end.call(env)
         end
       end

data/lib/grape/middleware/auth/strategy_info.rb

@@ -4,10 +4,10 @@ module Grape
   module Middleware
     module Auth
       StrategyInfo = Struct.new(:auth_class, :settings_fetcher) do
-        def create(app, options, &block)
+        def create(app, options, &)
           strategy_args = settings_fetcher.call(options)
 
-          auth_class.new(app, *strategy_args, &block)
+          auth_class.new(app, *strategy_args, &)
         end
       end
     end

data/lib/grape/middleware/base.rb

@@ -35,12 +35,7 @@ module Grape
         begin
           @app_response = @app.call(@env)
         ensure
-          begin
-            after_response = after
-          rescue StandardError => e
-            warn "caught error of type #{e.class} in after callback inside #{self.class.name} : #{e.message}"
-            raise e
-          end
+          after_response = reporting_after_errors { after }
         end
 
         response = after_response || @app_response
@@ -54,7 +49,7 @@ module Grape
 
       # @abstract
       # Called after the application is called in the middleware lifecycle.
-      # @return [Response, nil] a Rack SPEC response or nil to call the application afterwards.
+      # @return [Response, nil] a Rack SPEC response, or nil to keep the application's.
       def after; end
 
       def rack_request
@@ -79,13 +74,24 @@ module Grape
 
       private
 
+      # Runs what the middleware does once the app has answered. An error it
+      # raises is reported before it goes on: a +rescue_from :all+ handler
+      # turns it into a 500 without logging it, so this may be the only trace
+      # of it.
+      def reporting_after_errors
+        yield
+      rescue StandardError => e
+        warn "caught error of type #{e.class} in after callback inside #{self.class.name} : #{e.message}"
+        raise e
+      end
+
+      # +response+ is a Rack triplet, unless +after+ or the app handed back a
+      # Rack::Response.
       def merge_headers(response)
-        return if @header.blank?
+        return if @header.nil? || @header.empty?
+        return response.headers.merge!(@header) if response.is_a?(Rack::Response)
 
-        case response
-        when Rack::Response then response.headers.merge!(@header)
-        when Array          then response[1].merge!(@header)
-        end
+        response[1].merge!(@header)
       end
 
       def merge_default_options(options)
@@ -112,7 +118,7 @@ module Grape
       end
 
       def try_scrub(obj)
-        obj.respond_to?(:valid_encoding?) && !obj.valid_encoding? ? obj.scrub : obj
+        Grape::Util::Scrub.scrub(obj)
       end
     end
   end