grape 3.3.4 → 4.0.0

data/lib/grape/middleware/versioner/path.rb

@@ -23,22 +23,64 @@ module Grape
         end
 
         def before
-          path_info = Grape::Util::PathNormalizer.call(env[Rack::PATH_INFO])
+          routed = routed_version
+          return env[Grape::Env::API_VERSION] = routed if routed
+
+          path_info = env[Grape::Env::GRAPE_NORMALIZED_PATH] || Grape::Util::PathNormalizer.call(env[Rack::PATH_INFO])
           return if path_info == '/'
 
-          path_info = @prefixes.reduce(path_info) do |pi, path|
-            pi.start_with?(path) ? pi.delete_prefix(path) : pi
-          end
+          # `each` rather than `reduce`: Array does not override Enumerable's,
+          # so the generic accumulator path costs more than the work it drives
+          # on a list that holds at most a mount path and a prefix — and most
+          # often nothing at all.
+          @prefixes.each { |prefix| path_info = path_info.delete_prefix(prefix) if path_info.start_with?(prefix) }
 
           slash_position = path_info.index('/', 1) # omit the first one
-          return unless slash_position
+          return version_from_first_segment(path_info, slash_position) if slash_position
 
-          potential_version = path_info[1..(slash_position - 1)]
-          return unless potential_version.match?(pattern)
+          version_from_only_segment(path_info)
+        end
+
+        private
+
+        # Under path versioning every route pattern carries the version as a
+        # named capture (Pattern::Path#build_parts inserts it), constrained to
+        # the declared versions -- so the router has already sliced the segment
+        # out and validated it, and re-deriving it from PATH_INFO would repeat
+        # the normalize, prefix-strip and slice below for the same answer.
+        #
+        # Nil, and the path parsed as before, when there are no routing args at
+        # all (the middleware used outside a Grape router) and for the greedy
+        # routes behind auto-OPTIONS and 405, which capture nothing. An Array
+        # means the route declared a +:version+ segment of its own on top of the
+        # versioning one: Mustermann then reports the capture as every position
+        # it matched rather than the single segment recorded here, so that too
+        # is left to the path parse.
+        def routed_version
+          version = env[Grape::Env::GRAPE_ROUTING_ARGS]&.[](:version)
+          version if version.is_a?(String)
+        end
 
+        def version_from_first_segment(path_info, slash_position)
+          potential_version = path_info[1..(slash_position - 1)]
           version_not_found! unless potential_version_match?(potential_version)
           env[Grape::Env::API_VERSION] = potential_version
         end
+
+        # The path is a single segment (e.g. `GET /v1` — the root route of a
+        # path-versioned API). Nothing follows to disambiguate a version from a
+        # plain path or from a `.format` suffix (`/v1.json`), so the version is
+        # only recorded on an exact match against the declared versions, and an
+        # unmatched segment is left for the router to resolve — never a 404.
+        def version_from_only_segment(path_info)
+          candidate = path_info[1..]
+          candidate = candidate[0...candidate.rindex('.')] while candidate.include?('.') && !declared_version?(candidate)
+          env[Grape::Env::API_VERSION] = candidate if declared_version?(candidate)
+        end
+
+        def declared_version?(candidate)
+          versions.present? && versions.include?(candidate)
+        end
       end
     end
   end

data/lib/grape/namespace.rb

@@ -35,8 +35,9 @@ module Grape
       [self.class, space, requirements, options].hash
     end
 
-    # Join the namespaces from a list of settings to create a path prefix.
-    # @param settings [Array] list of Grape::Util::InheritableSettings.
+    # Join the namespaces from a list of Namespace objects to create a path
+    # prefix.
+    # @param settings [Array] list of Grape::Namespace objects.
     def self.joined_space_path(settings)
       JoinedSpaceCache[joined_space(settings)]
     end

data/lib/grape/path.rb

@@ -1,73 +1,12 @@
 # frozen_string_literal: true
 
 module Grape
-  # Represents a path to an endpoint.
-  class Path
-    DEFAULT_FORMAT_SEGMENT = '(/.:format)'
-    NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT = '(.:format)'
-    VERSION_SEGMENT = ':version'
-
-    attr_reader :origin, :suffix
-
-    def initialize(raw_path, raw_namespace, settings)
-      @origin = PartsCache[build_parts(raw_path, raw_namespace, settings)]
-      @suffix = build_suffix(raw_path, raw_namespace, settings)
-    end
-
-    def to_s
-      "#{origin}#{suffix}"
-    end
-
-    private
-
-    def build_suffix(raw_path, raw_namespace, settings)
-      return "(.#{settings[:format]})" if uses_specific_format?(settings)
-      return NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT if !uses_path_versioning?(settings) || valid_part?(raw_namespace) || valid_part?(raw_path)
-
-      DEFAULT_FORMAT_SEGMENT
-    end
-
-    def build_parts(raw_path, raw_namespace, settings)
-      parts = []
-      add_part(parts, settings[:mount_path])
-      add_part(parts, settings[:root_prefix])
-      parts << VERSION_SEGMENT if uses_path_versioning?(settings)
-      add_part(parts, raw_namespace)
-      add_part(parts, raw_path)
-      parts
-    end
-
-    def add_part(parts, value)
-      parts << value if value && not_slash?(value)
-    end
-
-    def not_slash?(value)
-      value != '/'
-    end
-
-    def uses_specific_format?(settings)
-      return false unless settings.key?(:format) && settings.key?(:content_types)
-
-      settings[:format] && Array(settings[:content_types]).size == 1
-    end
-
-    def uses_path_versioning?(settings)
-      return false unless settings.key?(:version) && settings[:version_options]
-
-      settings[:version] && settings[:version_options].using == :path
-    end
-
-    def valid_part?(part)
-      part&.match?(/^\S/) && not_slash?(part)
-    end
-
-    class PartsCache < Grape::Util::Cache
-      def initialize
-        super
-        @cache = Hash.new do |h, parts|
-          h[parts] = Grape::Util::PathNormalizer.call(parts.join('/'))
-        end
-      end
-    end
-  end
+  # @deprecated +Grape::Path+ moved to {Grape::Router::Pattern::Path}, since it
+  #   is a router-internal detail that only exists to build a
+  #   {Grape::Router::Pattern}. Reference the new constant instead.
+  Path = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
+    'Grape::Path',
+    'Grape::Router::Pattern::Path',
+    Grape.deprecator
+  )
 end

data/lib/grape/precompiled_json.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Grape
+  # Marks a body as JSON that has already been rendered, so the JSON formatters
+  # serve it verbatim instead of encoding it a second time.
+  #
+  # +Grape::Formatter::Json+ calls +to_json+ on whatever the endpoint returned, so a
+  # String holding pre-rendered JSON — a blob cached in Redis, a +json_agg+ column read
+  # straight from Postgres, output from another serializer — comes back encoded twice:
+  #
+  #   '{"a":1}'  =>  "\"{\\\"a\\\":1}\""
+  #
+  # Wrapping the body opts that one response out of encoding:
+  #
+  #   get '/cached' do
+  #     body Grape::PrecompiledJson.new(Rails.cache.read('payload'))
+  #   end
+  #
+  # An Array is joined into a JSON array without its members being parsed, which is
+  # what makes a cached collection cheap — N rendered blobs are spliced together
+  # rather than round-tripped:
+  #
+  #   Grape::PrecompiledJson.new(['{"id":1}', '{"id":2}']).to_s # => '[{"id":1},{"id":2}]'
+  #
+  # +Array#join+ calls +to_s+ on each member, so members may themselves be
+  # +PrecompiledJson+ instances.
+  #
+  # Wrap only the whole body. A wrapper nested inside a Hash or Array that is then
+  # handed to an encoder is serialized as an ordinary object — +ActiveSupport::JSON+
+  # renders it through +as_json+ as +{"value":"{\"a\":1}"}+ — because no encoder knows
+  # to unwrap it. Nothing checks that the String actually holds JSON; that is the
+  # caller's responsibility.
+  class PrecompiledJson
+    # @param value [String, Array<String>] pre-rendered JSON
+    def initialize(value)
+      @value = value
+    end
+
+    # @return [String] the JSON to serve
+    # @raise [Grape::Exceptions::InvalidFormatter] if the value is neither a String
+    #   nor an Array; the formatter middleware turns this into a 500 rather than
+    #   letting a body Rack cannot serve reach the SPEC check.
+    def to_s
+      return @value if @value.is_a?(String)
+      return "[#{@value.join(',')}]" if @value.is_a?(Array)
+
+      raise Grape::Exceptions::InvalidFormatter.new(@value.class, 'json')
+    end
+  end
+end

data/lib/grape/request.rb

@@ -141,7 +141,7 @@ module Grape
 
     def initialize(env, build_params_with: nil)
       super(env)
-      @params_builder = Grape::ParamsBuilder.params_builder_for(build_params_with || Grape.config.param_builder)
+      @build_params_with = build_params_with
     end
 
     def params
@@ -166,10 +166,17 @@ module Grape
 
     private
 
+    # Resolved on first use rather than in the constructor: a request that never
+    # reads +params+ -- an endpoint with no validations whose block does not ask
+    # for them -- pays neither the registry lookup nor the global config read,
+    # and every request builds a Grape::Request.
+    def params_builder
+      @params_builder ||= Grape::ParamsBuilder.params_builder_for(@build_params_with || Grape.config[:param_builder])
+    end
+
     def make_params
-      params = @params_builder.call(rack_params)
-      routing_args = env[Grape::Env::GRAPE_ROUTING_ARGS]
-      filtered = routing_args&.except(:version, :route_info)
+      params = params_builder.call(rack_params)
+      filtered = routing_args_as_params(env[Grape::Env::GRAPE_ROUTING_ARGS])
       return params if filtered.blank?
 
       params.deep_merge!(filtered)
@@ -177,6 +184,31 @@ module Grape
       raise Grape::Exceptions::RequestError
     end
 
+    # The routing args carry two things that are not request params:
+    # +:route_info+, which is always Grape's own, and +:version+, which is only
+    # Grape's own when the API declared a version — that is captured as a path
+    # segment and exposed through +env['api.version']+ instead.
+    #
+    # An API that declares no version can legitimately name a param +:version+
+    # (`route_param :version`, `get '/:version'`), and that capture belongs to
+    # the application. Dropping it unconditionally left `params[:version]` nil
+    # on a route that had matched, losing the segment silently.
+    def routing_args_as_params(routing_args)
+      return if routing_args.nil?
+      return routing_args.except(:version, :route_info) if grape_owns_version?(routing_args)
+
+      routing_args.except(:route_info)
+    end
+
+    # A route reports a +version+ only when the API declared one, which is the
+    # case where the captured segment is Grape's rather than the application's.
+    def grape_owns_version?(routing_args)
+      return false unless routing_args.key?(:version)
+
+      route = routing_args[:route_info]
+      route.respond_to?(:version) && !route.version.nil?
+    end
+
     # Uses a plain `each_header` block instead of `each_header.with_object`:
     # `with_object` can only pass the block one value plus the memo, so the
     # `k, v` pair would be boxed into a throwaway Array on every header. A

data/lib/grape/router/base_route.rb

@@ -7,34 +7,71 @@ module Grape
 
       delegate_missing_to :@options
 
-      attr_reader :options, :pattern
+      attr_reader :options, :pattern, :prefix, :settings, :namespace
 
-      def_delegators :@pattern, :path, :origin
-      def_delegators :@options, :description, :version, :requirements, :prefix, :anchor, :settings, :forward_match, *Grape::Util::ApiDescription::DSL_METHODS
+      # +version+, +anchor+ and +requirements+ shape the matcher, so they are
+      # read from the pattern rather than stored again on the route.
+      def_delegators :@pattern, :path, :origin, :version, :anchor, :requirements
+      def_delegators :@options, :description, *Grape::Util::ApiDescription::DSL_METHODS
 
-      def initialize(pattern, options = {})
+      def initialize(pattern, options = {}, namespace: nil, prefix: nil, settings: nil)
         @pattern = pattern
         @options = options.is_a?(ActiveSupport::OrderedOptions) ? options : ActiveSupport::OrderedOptions.new.update(options)
+        @namespace = namespace
+        @prefix = prefix
+        @settings = settings
       end
 
-      # see https://github.com/ruby-grape/grape/issues/1348
-      def namespace
-        @namespace ||= @options[:namespace]
+      # +success+ and +failure+ are the +desc+ DSL's names for +entity+ and
+      # +http_codes+: the block form writes the canonical key, a keyword option
+      # keeps the name it was written with, so both spellings are read here.
+      # Without this they resolve through +delegate_missing_to+, which answers
+      # nil for whichever of the two keys the description did not use.
+      def success
+        @options[:entity] || @options[:success]
       end
 
-      def regexp_capture_index
-        @regexp_capture_index ||= CaptureIndexCache[@index]
+      def failure
+        @options[:http_codes] || @options[:failure]
       end
 
+      # @deprecated Use {#default_response}, the name grape-swagger asks for.
+      #   This one has to be written out rather than delegated like the rest:
+      #   an ActiveSupport::OrderedOptions answers an unknown name with that
+      #   key's value, but +default+ is not unknown to it — it is +Hash#default+,
+      #   the Hash's own default value — so a delegator would report nil for
+      #   every route.
+      def default
+        Grape.deprecator.warn('`Grape::Router::Route#default` is deprecated. Use `#default_response` instead.')
+        default_response
+      end
+
+      # Assigned eagerly in {#to_regexp} (router compilation) rather than
+      # memoized here: this reader is called from request-time route matching
+      # on instances shared across threads, so it must not write state.
+      attr_reader :regexp_capture_index
+
+      # The number of the group this route occupies in the union the router
+      # compiled it into. Only the union can say what it is, so it is written
+      # back by {Router#compile!} right after building one, and like
+      # +regexp_capture_index+ it is never assigned at request time.
+      attr_reader :regexp_capture_group
+
       def pattern_regexp
         @pattern.to_regexp
       end
 
       def to_regexp(index)
-        @index = index
+        @regexp_capture_index = CaptureIndexCache[index]
         Regexp.new("(?<#{regexp_capture_index}>#{pattern_regexp})")
       end
 
+      # @api private
+      # @see #regexp_capture_group
+      def resolve_capture_group!(union_named_captures)
+        @regexp_capture_group = union_named_captures.fetch(regexp_capture_index).first
+      end
+
       class CaptureIndexCache < Grape::Util::Cache
         def initialize
           super

data/lib/grape/router/greedy_route.rb

@@ -18,7 +18,11 @@ module Grape
         @allow_header = allow_header
       end
 
-      def params(_input = nil)
+      def params
+        nil
+      end
+
+      def params_for(_input)
         nil
       end
     end

data/lib/grape/router/pattern/path.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Grape
+  class Router
+    class Pattern
+      # Assembles the path template a {Pattern} compiles into a matcher. It turns
+      # a raw path plus the path-settings snapshot taken by
+      # {Grape::Util::InheritableSetting#path_settings} (mount paths, root
+      # prefix, path-versioning and format) into an +origin+ (the route prefix)
+      # and a +suffix+ (the format segment). {Pattern.build} is the entry point
+      # that wires this into pattern construction.
+      class Path
+        DEFAULT_FORMAT_SEGMENT = '(/.:format)'
+        NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT = '(.:format)'
+        VERSION_SEGMENT = ':version'
+
+        attr_reader :origin, :suffix
+
+        def initialize(raw_path, raw_namespace, settings)
+          @origin = PartsCache[build_parts(raw_path, raw_namespace, settings)]
+          @suffix = build_suffix(raw_path, raw_namespace, settings)
+        end
+
+        def to_s
+          "#{origin}#{suffix}"
+        end
+
+        private
+
+        def build_suffix(raw_path, raw_namespace, settings)
+          return "(.#{settings.format})" if uses_specific_format?(settings)
+          return NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT if !uses_path_versioning?(settings) || valid_part?(raw_namespace) || valid_part?(raw_path)
+
+          DEFAULT_FORMAT_SEGMENT
+        end
+
+        def build_parts(raw_path, raw_namespace, settings)
+          parts = []
+          add_part(parts, settings.mount_path)
+          add_part(parts, settings.root_prefix)
+          parts << VERSION_SEGMENT if uses_path_versioning?(settings)
+          add_part(parts, raw_namespace)
+          add_part(parts, raw_path)
+          parts
+        end
+
+        def add_part(parts, value)
+          parts << value if value && not_slash?(value)
+        end
+
+        def not_slash?(value)
+          value != '/'
+        end
+
+        def uses_specific_format?(settings)
+          settings.format && Array(settings.content_types).size == 1
+        end
+
+        def uses_path_versioning?(settings)
+          settings.version && settings.version_options&.using == :path
+        end
+
+        def valid_part?(part)
+          part&.match?(/\A\S/) && not_slash?(part)
+        end
+
+        class PartsCache < Grape::Util::Cache
+          def initialize
+            super
+            @cache = Hash.new do |h, parts|
+              h[parts] = Grape::Util::PathNormalizer.call(parts.join('/'))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/router/pattern.rb

@@ -7,17 +7,43 @@ module Grape
 
       DEFAULT_CAPTURES = %w[format version].freeze
 
-      attr_reader :origin, :path, :pattern, :to_regexp
+      attr_reader :origin, :path, :pattern, :to_regexp, :anchor, :version, :requirements
 
       def_delegators :pattern, :params
       def_delegators :to_regexp, :===
       alias match? ===
 
-      def initialize(origin:, suffix:, anchor:, params:, format:, version:, requirements:)
+      # Build a Pattern from a raw path, namespace and the API's inheritable
+      # settings. {Path} owns the settings-aware assembly of +origin+/+suffix+;
+      # the Pattern itself stays value-based (see {#initialize}).
+      def self.build(path:, namespace:, settings:, anchor:, params:, version:, requirements:)
+        built_path = Path.new(path, namespace, settings)
+        new(origin: built_path.origin, suffix: built_path.suffix, anchor:, params:, version:, requirements:)
+      end
+
+      def initialize(origin:, suffix:, anchor:, params:, version:, requirements:)
         @origin = origin
+        @anchor = anchor
+        @version = version
+        @requirements = requirements
         @path = PatternCache[[build_path_from_pattern(@origin, anchor), suffix]]
-        @pattern = MustermannPattern.new(@path, uri_decode: true, params:, capture: extract_capture(format, version, requirements))
+        @pattern = MustermannPattern.new(@path, uri_decode: true, params:, capture: extract_capture(version, requirements))
         @to_regexp = @pattern.to_regexp
+        @captures = @to_regexp.names.any?
+      end
+
+      # True when the compiled pattern has named captures to extract from a
+      # matched path. A fully static path has none — not even +format+, which
+      # the suffix spells as a literal — so asking Mustermann for its params
+      # would run the regexp a second time (the router's union already matched
+      # it) only to hand back an empty Hash.
+      #
+      # Resolved once here rather than per request: +Regexp#names+ builds an
+      # Array and a String per capture, and Ruby offers no predicate that skips
+      # that (+named_captures+ builds a Hash, and scanning the source for
+      # <tt>(?<</tt> would count lookbehinds, which name nothing).
+      def captures?
+        @captures
       end
 
       def captures_default
@@ -28,14 +54,38 @@ module Grape
 
       private
 
-      def extract_capture(format, version, requirements)
-        capture = {}
-        capture[:format] = map_str(format) if format.present?
-        capture[:version] = map_str(version) if version.present?
+      # The declared versions constrain the +:version+ capture. They are handed
+      # to Mustermann as one alternation Regexp rather than as the Array of
+      # Strings they arrive in, because an Array capture makes Mustermann build
+      # a *converter* for the capture -- and for an Array of plain Strings that
+      # converter is the identity function (Mustermann only derives one from a
+      # Class or a Symbol, so every entry contributes nothing and the lambda
+      # falls through to `|| string`).
+      #
+      # A non-empty converter table costs every request on the route: it makes
+      # Mustermann's +identity_params?+ fast path unreachable, so +params+
+      # rebuilds the capture Hash through +map_param+ and calls the do-nothing
+      # lambda on each value. Passing a Regexp registers no converter at all.
+      #
+      # The generated matcher differs in one respect: Mustermann expands an
+      # Array entry the way it expands a path literal, so each character also
+      # matches its own percent-encoding (+v1+ as <tt>(?:v|%76)(?:1|%31)</tt>).
+      # A Regexp is inserted verbatim, so a percent-encoded version segment no
+      # longer matches the route. It never reached the endpoint anyway --
+      # {Versioner::Base#potential_version_match?} compares the raw segment
+      # against the declared versions, so +/api/%76%31/x+ was matched here and
+      # then rejected as an unknown version, ending in the same cascading 404
+      # the router now returns directly.
+      #
+      # +Regexp.union+ takes Strings and Regexps only, and +version+ accepts
+      # Symbols and Integers too, so the entries are coerced first. A lone one
+      # would survive without it -- the single-argument path goes through
+      # +Regexp.escape+, which does accept a Symbol -- but a second raises
+      # TypeError.
+      def extract_capture(version, requirements)
+        return requirements if version.blank?
 
-        return capture if requirements.blank?
-
-        requirements.merge(capture)
+        requirements.merge(version: Regexp.union(Array.wrap(version).map(&:to_s)))
       end
 
       def build_path_from_pattern(pattern, anchor)
@@ -46,10 +96,6 @@ module Grape
         "#{pattern}/?*path"
       end
 
-      def map_str(value)
-        Array.wrap(value).map(&:to_s)
-      end
-
       class PatternCache < Grape::Util::Cache
         def initialize
           super

data/lib/grape/router/route.rb

@@ -12,15 +12,18 @@ module Grape
 
       def_delegators :@app, :call
 
-      def initialize(endpoint, method, pattern, options)
-        super(pattern, options)
+      def initialize(endpoint, method, pattern, options, forward_match:, params: {}, **route_attributes)
+        super(pattern, options, **route_attributes)
         @app = endpoint
         @request_method = upcase_method(method)
-        @match_function = options[:forward_match] ? FORWARD_MATCH_METHOD : NON_FORWARD_MATCH_METHOD
+        @match_function = forward_match ? FORWARD_MATCH_METHOD : NON_FORWARD_MATCH_METHOD
+        @declared_params = params
       end
 
-      def convert_to_head_request!
-        @request_method = Rack::HEAD
+      def to_head
+        head = dup
+        head.convert_to_head_request!
+        head
       end
 
       def apply(app)
@@ -34,19 +37,68 @@ module Grape
         @match_function.call(input, pattern)
       end
 
-      def params(input = nil)
-        return params_without_input if input.blank?
+      # The route's declared params keyed by name — path captures plus any
+      # declared body/query params, as their definitions. Used for documentation
+      # (e.g. grape-swagger), not for extracting request values.
+      def params
+        @params ||= pattern.captures_default.merge(@declared_params)
+      end
+
+      # Extract param values from a matched request path. Used by the router.
+      #
+      # A pattern with no named captures has nothing to extract, so it skips the
+      # match entirely and answers nil — the same way {GreedyRoute#params_for}
+      # does, and what the router already coerces into the Hash it builds
+      # routing args in.
+      def params_for(input)
+        return unless pattern.captures?
 
         parsed = pattern.params(input)
         return unless parsed
 
-        parsed.compact.symbolize_keys
+        params = {}
+        parsed.each { |name, value| params[name.to_sym] = tag_utf8!(value) unless value.nil? }
+        params
+      end
+
+      protected
+
+      def convert_to_head_request!
+        @request_method = Rack::HEAD
       end
 
       private
 
-      def params_without_input
-        @params_without_input ||= pattern.captures_default.merge(options[:params])
+      # Mustermann decodes path captures out of +PATH_INFO+, which Rack hands us
+      # tagged ASCII-8BIT, so path params came back binary while Rack tags query
+      # and body params UTF-8. That split makes an API's own declarations
+      # disagree with themselves: `values: ['café']` matched `?id=café` but not
+      # `/café`, since a binary string never equals the UTF-8 literal it was
+      # written as.
+      #
+      # Re-tag as UTF-8. Nothing obliges a client to send UTF-8: the request
+      # target is octets to HTTP, and Rack's SPEC has CGI keys carry non-ASCII
+      # as ASCII-8BIT. But UTF-8 is what browsers percent-encode with, what an
+      # IRI maps to, and what Rails settles on — ActionDispatch::Journey::Router
+      # force_encodes every path capture to UTF-8 after unescaping it.
+      #
+      # Only the encoding changes; the bytes are untouched. Octets that are not
+      # UTF-8 therefore stay invalid and are caught downstream rather than being
+      # silently scrubbed into something the client never sent.
+      #
+      # The re-tag is in place, hence the bang. Mustermann's +Pattern#params+
+      # builds a fresh Hash of fresh, unfrozen strings on every call and skips
+      # its own Match cache, so the mutation cannot escape this request — which
+      # is also what lets the Array branch re-tag its elements with +each+.
+      def tag_utf8!(value)
+        case value
+        when String
+          value.force_encoding(Encoding::UTF_8)
+        when Array
+          value.each { |v| tag_utf8!(v) }
+        else
+          value
+        end
       end
 
       def upcase_method(method)