Deprecates Grape's Extensions for ParamsBuilder in favor of build_with (#2540)

ericproulx · web-flow · commit 45abe0dd9f18 · 2025-03-01T08:41:03.000-05:00
* Deprecates Grape's Extensions for ParamsBuilder in favor of build_with
Adds params_builder.rb registration process
Update README.md
Update UPGRADING.md
Add exceptions query_parsing.rb and unknown_params_builder.rb

* Fix hashie specs

* Fix cops

* Remove query_parsing part

* Fix has has

* Revert Grape.config.param_builder

* Add CHANGELOG.md

* Fixes
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 * [#2535](https://github.com/ruby-grape/grape/pull/2535): Delegates calls to inner objects - [@ericproulx](https://github.com/ericproulx).
 * [#2537](https://github.com/ruby-grape/grape/pull/2537): Use activesupport `try` pattern - [@ericproulx](https://github.com/ericproulx).
 * [#2536](https://github.com/ruby-grape/grape/pull/2536): Update normalize_path like Rails - [@ericproulx](https://github.com/ericproulx).
+* [#2540](https://github.com/ruby-grape/grape/pull/2540): Introduce Params builder with symbolized short name - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
 
 #### Fixes
diff --git a/README.md b/README.md
@@ -719,10 +719,13 @@ For example, for the `param_builder`, the following code could run in an initial
 
 ```ruby
 Grape.configure do |config|
-  config.param_builder = Grape::Extensions::Hashie::Mash::ParamBuilder
+  config.param_builder = :hashie_mash
 end
 ```
 
+Available parameter builders are `:hash`, `:hash_with_indifferent_access`, and `:hashie_mash`.
+See [params_builder](lib/grape/params_builder).
+
 You can also configure a single API:
 
 ```ruby
@@ -789,7 +792,7 @@ By default parameters are available as `ActiveSupport::HashWithIndifferentAccess
 
 ```ruby
 class API < Grape::API
-  include Grape::Extensions::Hashie::Mash::ParamBuilder
+  build_with :hashie_mash
 
   params do
     optional :color, type: String
@@ -803,16 +806,15 @@ The class can also be overridden on individual parameter blocks using `build_wit
 
 ```ruby
 params do
-  build_with Grape::Extensions::Hash::ParamBuilder
+  build_with :hash
   optional :color, type: String
 end
 ```
 
-Or globally with the [Configuration](#configuration) `Grape.configure.param_builder`.
-
 In the example above, `params["color"]` will return `nil` since `params` is a plain `Hash`.
 
-Available parameter builders are `Grape::Extensions::Hash::ParamBuilder`, `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder` and `Grape::Extensions::Hashie::Mash::ParamBuilder`.
+Available parameter builders are `:hash`, `:hash_with_indifferent_access`, and `:hashie_mash`.
+See [params_builder](lib/grape/params_builder).
 
 ### Declared
 
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -1,6 +1,11 @@
 Upgrading Grape
 ===============
 
+#### Params Builder
+
+- Passing a class to `build_with` or `Grape.config.param_builder` has been deprecated in favor of a symbolized short_name. See `SHORTNAME_LOOKUP` in [params_builder](lib/grape/params_builder.rb).
+- Including Grape's extensions like `Grape::Extensions::Hashie::Mash::ParamBuilder` has been deprecated in favor of using `build_with` at the route level.
+
 ### Upgrading to >= 2.4.0
 
 #### Custom Validators
diff --git a/lib/grape.rb b/lib/grape.rb
@@ -64,7 +64,7 @@ def self.deprecator
   end
 
   configure do |config|
-    config.param_builder = Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder
+    config.param_builder = :hash_with_indifferent_access
     config.compile_methods!
   end
 end
diff --git a/lib/grape/dsl/parameters.rb b/lib/grape/dsl/parameters.rb
@@ -23,14 +23,14 @@ module Parameters
       #     class API < Grape::API
       #       desc "Get collection"
       #       params do
-      #         build_with Grape::Extensions::Hashie::Mash::ParamBuilder
+      #         build_with :hashie_mash
       #         requires :user_id, type: Integer
       #       end
       #       get do
       #         params['user_id']
       #       end
       #     end
-      def build_with(build_with = nil)
+      def build_with(build_with)
         @api.namespace_inheritable(:build_params_with, build_with)
       end
 
diff --git a/lib/grape/dsl/routing.rb b/lib/grape/dsl/routing.rb
@@ -67,6 +67,10 @@ def scope(_name = nil, &block)
           end
         end
 
+        def build_with(build_with)
+          namespace_inheritable(:build_params_with, build_with)
+        end
+
         # Do not route HEAD requests to GET requests automatically.
         def do_not_route_head!
           namespace_inheritable(:do_not_route_head, true)
diff --git a/lib/grape/exceptions/unknown_params_builder.rb b/lib/grape/exceptions/unknown_params_builder.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module Exceptions
+    class UnknownParamsBuilder < Base
+      def initialize(params_builder_type)
+        super(message: compose_message(:unknown_params_builder, params_builder_type: params_builder_type))
+      end
+    end
+  end
+end
diff --git a/lib/grape/extensions/active_support/hash_with_indifferent_access.rb b/lib/grape/extensions/active_support/hash_with_indifferent_access.rb
@@ -8,11 +8,8 @@ module ParamBuilder
           extend ::ActiveSupport::Concern
 
           included do
-            namespace_inheritable(:build_params_with, Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder)
-          end
-
-          def params_builder
-            Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder
+            Grape.deprecator.warn 'This concern has been deprecated. Use `build_with` with one of the following short_name (:hash, :hash_with_indifferent_access, :hashie_mash) instead.'
+            namespace_inheritable(:build_params_with, :hash_with_indifferent_access)
           end
 
           def build_params
diff --git a/lib/grape/extensions/hash.rb b/lib/grape/extensions/hash.rb
@@ -7,7 +7,8 @@ module ParamBuilder
         extend ::ActiveSupport::Concern
 
         included do
-          namespace_inheritable(:build_params_with, Grape::Extensions::Hash::ParamBuilder)
+          Grape.deprecator.warn 'This concern has been deprecated. Use `build_with` with one of the following short_name (:hash, :hash_with_indifferent_access, :hashie_mash) instead.'
+          namespace_inheritable(:build_params_with, :hash)
         end
 
         def build_params
diff --git a/lib/grape/extensions/hashie/mash.rb b/lib/grape/extensions/hashie/mash.rb
@@ -6,12 +6,10 @@ module Hashie
       module Mash
         module ParamBuilder
           extend ::ActiveSupport::Concern
-          included do
-            namespace_inheritable(:build_params_with, Grape::Extensions::Hashie::Mash::ParamBuilder)
-          end
 
-          def params_builder
-            Grape::Extensions::Hashie::Mash::ParamBuilder
+          included do
+            Grape.deprecator.warn 'This concern has been deprecated. Use `build_with` with one of the following short_name (:hash, :hash_with_indifferent_access, :hashie_mash) instead.'
+            namespace_inheritable(:build_params_with, :hashie_mash)
           end
 
           def build_params
diff --git a/lib/grape/locale/en.yml b/lib/grape/locale/en.yml
@@ -33,6 +33,7 @@ en:
           problem: 'unknown :using for versioner: %{strategy}'
           resolution: 'available strategy for :using is :path, :header, :accept_version_header, :param'
         unknown_validator: 'unknown validator: %{validator_type}'
+        unknown_params_builder: 'unknown params_builder: %{params_builder_type}'
         unknown_options: 'unknown options: %{options}'
         unknown_parameter: 'unknown parameter: %{param}'
         incompatible_option_values: '%{option1}: %{value1} is incompatible with %{option2}: %{value2}'
@@ -57,3 +58,4 @@ en:
           problem: 'invalid version header'
           resolution: '%{message}'
         invalid_response: 'Invalid response'
+        query_parsing: 'query params are not parsable'
diff --git a/lib/grape/params_builder.rb b/lib/grape/params_builder.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Grape
+  module ParamsBuilder
+    extend Grape::Util::Registry
+
+    SHORT_NAME_LOOKUP = {
+      'Grape::Extensions::Hash::ParamBuilder' => :hash,
+      'Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder' => :hash_with_indifferent_access,
+      'Grape::Extensions::Hashie::Mash::ParamBuilder' => :hashie_mash
+    }.freeze
+
+    module_function
+
+    def params_builder_for(short_name)
+      verified_short_name = verify_short_name!(short_name)
+
+      raise Grape::Exceptions::UnknownParamsBuilder, verified_short_name unless registry.key?(verified_short_name)
+
+      registry[verified_short_name]
+    end
+
+    def verify_short_name!(short_name)
+      return short_name if short_name.is_a?(Symbol)
+
+      class_name = short_name.name
+      SHORT_NAME_LOOKUP[class_name].tap do |real_short_name|
+        Grape.deprecator.warn "#{class_name} has been deprecated. Use short name :#{real_short_name} instead."
+      end
+    end
+  end
+end
diff --git a/lib/grape/params_builder/base.rb b/lib/grape/params_builder/base.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Grape
+  module ParamsBuilder
+    class Base
+      class << self
+        def call(_params)
+          raise NotImplementedError
+        end
+
+        def inherited(klass)
+          super
+          ParamsBuilder.register(klass)
+        end
+      end
+    end
+  end
+end
diff --git a/lib/grape/params_builder/hash.rb b/lib/grape/params_builder/hash.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module ParamsBuilder
+    class Hash < Base
+      def self.call(params)
+        params.deep_symbolize_keys
+      end
+    end
+  end
+end
diff --git a/lib/grape/params_builder/hash_with_indifferent_access.rb b/lib/grape/params_builder/hash_with_indifferent_access.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module ParamsBuilder
+    class HashWithIndifferentAccess < Base
+      def self.call(params)
+        params.with_indifferent_access
+      end
+    end
+  end
+end
diff --git a/lib/grape/params_builder/hashie_mash.rb b/lib/grape/params_builder/hashie_mash.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Grape
+  module ParamsBuilder
+    class HashieMash < Base
+      def self.call(params)
+        ::Hashie::Mash.new(params)
+      end
+    end
+  end
+end
diff --git a/lib/grape/request.rb b/lib/grape/request.rb
@@ -2,32 +2,38 @@
 
 module Grape
   class Request < Rack::Request
+    DEFAULT_PARAMS_BUILDER = :hash_with_indifferent_access
     HTTP_PREFIX = 'HTTP_'
 
     alias rack_params params
 
     def initialize(env, build_params_with: nil)
-      extend build_params_with || Grape.config.param_builder
       super(env)
+      @params_builder = Grape::ParamsBuilder.params_builder_for(build_params_with || Grape.config.param_builder)
     end
 
     def params
-      @params ||= build_params
-    rescue EOFError
-      raise Grape::Exceptions::EmptyMessageBody.new(content_type)
-    rescue Rack::Multipart::MultipartPartLimitError
-      raise Grape::Exceptions::TooManyMultipartFiles.new(Rack::Utils.multipart_part_limit)
+      @params ||= make_params
     end
 
     def headers
       @headers ||= build_headers
     end
 
-    private
-
+    # needs to be public until extensions param_builder are removed
     def grape_routing_args
       # preserve version from query string parameters
-      env[Grape::Env::GRAPE_ROUTING_ARGS].except(:version, :route_info)
+      env[Grape::Env::GRAPE_ROUTING_ARGS]&.except(:version, :route_info) || {}
+    end
+
+    private
+
+    def make_params
+      @params_builder.call(rack_params).deep_merge!(grape_routing_args)
+    rescue EOFError
+      raise Grape::Exceptions::EmptyMessageBody.new(content_type)
+    rescue Rack::Multipart::MultipartPartLimitError
+      raise Grape::Exceptions::TooManyMultipartFiles.new(Rack::Utils.multipart_part_limit)
     end
 
     def build_headers
diff --git a/spec/grape/api_spec.rb b/spec/grape/api_spec.rb
@@ -4694,4 +4694,25 @@ def uniqe_id_route
 
     it { is_expected.to be_bad_request }
   end
+
+  describe '.build_with' do
+    let(:app) do
+      Class.new(described_class) do
+        build_with :unknown
+        params do
+          requires :a_param, type: Integer
+        end
+        get
+      end
+    end
+
+    before do
+      get '/'
+    end
+
+    it 'raises an UnknownParamsBuilder error' do
+      expect(last_response).to be_server_error
+      expect(last_response.body).to eq('unknown params_builder: unknown')
+    end
+  end
 end
diff --git a/spec/grape/endpoint/declared_spec.rb b/spec/grape/endpoint/declared_spec.rb
@@ -46,7 +46,7 @@
     context 'when params are not built with default class' do
       it 'returns an object that corresponds with the params class - hash with indifferent access' do
         subject.params do
-          build_with Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder
+          build_with :hash_with_indifferent_access
         end
         subject.get '/declared' do
           d = declared(params, include_missing: true)
@@ -59,7 +59,7 @@
 
       it 'returns an object that corresponds with the params class - hash' do
         subject.params do
-          build_with Grape::Extensions::Hash::ParamBuilder
+          build_with :hash
         end
         subject.get '/declared' do
           d = declared(params, include_missing: true)
diff --git a/spec/grape/extensions/param_builders/hash_spec.rb b/spec/grape/extensions/param_builders/hash_spec.rb
diff --git a/spec/grape/extensions/param_builders/hash_with_indifferent_access_spec.rb b/spec/grape/extensions/param_builders/hash_with_indifferent_access_spec.rb
diff --git a/spec/grape/grape_spec.rb b/spec/grape/grape_spec.rb
diff --git a/spec/grape/params_builder/hash_spec.rb b/spec/grape/params_builder/hash_spec.rb
diff --git a/spec/grape/params_builder/hash_with_indifferent_access_spec.rb b/spec/grape/params_builder/hash_with_indifferent_access_spec.rb
diff --git a/spec/grape/request_spec.rb b/spec/grape/request_spec.rb
diff --git a/spec/integration/hashie/hashie_spec.rb b/spec/integration/hashie/hashie_spec.rb
