actionpack 7.2.3.1 → 8.1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +606 -120
  3. data/lib/abstract_controller/asset_paths.rb +4 -2
  4. data/lib/abstract_controller/base.rb +11 -5
  5. data/lib/abstract_controller/caching.rb +6 -3
  6. data/lib/abstract_controller/callbacks.rb +6 -0
  7. data/lib/abstract_controller/logger.rb +2 -1
  8. data/lib/abstract_controller/rendering.rb +0 -1
  9. data/lib/action_controller/api.rb +1 -0
  10. data/lib/action_controller/base.rb +3 -2
  11. data/lib/action_controller/caching.rb +1 -2
  12. data/lib/action_controller/form_builder.rb +4 -4
  13. data/lib/action_controller/log_subscriber.rb +22 -3
  14. data/lib/action_controller/metal/allow_browser.rb +12 -2
  15. data/lib/action_controller/metal/conditional_get.rb +30 -1
  16. data/lib/action_controller/metal/data_streaming.rb +5 -5
  17. data/lib/action_controller/metal/exceptions.rb +5 -0
  18. data/lib/action_controller/metal/flash.rb +1 -4
  19. data/lib/action_controller/metal/head.rb +3 -1
  20. data/lib/action_controller/metal/http_authentication.rb +1 -1
  21. data/lib/action_controller/metal/instrumentation.rb +1 -2
  22. data/lib/action_controller/metal/live.rb +83 -31
  23. data/lib/action_controller/metal/permissions_policy.rb +9 -0
  24. data/lib/action_controller/metal/rate_limiting.rb +39 -9
  25. data/lib/action_controller/metal/redirecting.rb +107 -14
  26. data/lib/action_controller/metal/renderers.rb +29 -9
  27. data/lib/action_controller/metal/rendering.rb +16 -3
  28. data/lib/action_controller/metal/request_forgery_protection.rb +18 -10
  29. data/lib/action_controller/metal/rescue.rb +9 -0
  30. data/lib/action_controller/metal/streaming.rb +5 -84
  31. data/lib/action_controller/metal/strong_parameters.rb +294 -98
  32. data/lib/action_controller/railtie.rb +35 -15
  33. data/lib/action_controller/structured_event_subscriber.rb +116 -0
  34. data/lib/action_controller/test_case.rb +12 -2
  35. data/lib/action_dispatch/http/cache.rb +143 -12
  36. data/lib/action_dispatch/http/content_security_policy.rb +14 -1
  37. data/lib/action_dispatch/http/filter_parameters.rb +5 -3
  38. data/lib/action_dispatch/http/mime_negotiation.rb +66 -2
  39. data/lib/action_dispatch/http/mime_types.rb +1 -0
  40. data/lib/action_dispatch/http/param_builder.rb +187 -0
  41. data/lib/action_dispatch/http/param_error.rb +26 -0
  42. data/lib/action_dispatch/http/parameters.rb +3 -3
  43. data/lib/action_dispatch/http/permissions_policy.rb +8 -1
  44. data/lib/action_dispatch/http/query_parser.rb +55 -0
  45. data/lib/action_dispatch/http/request.rb +70 -21
  46. data/lib/action_dispatch/http/response.rb +52 -17
  47. data/lib/action_dispatch/http/url.rb +112 -16
  48. data/lib/action_dispatch/journey/formatter.rb +5 -0
  49. data/lib/action_dispatch/journey/gtg/simulator.rb +33 -12
  50. data/lib/action_dispatch/journey/gtg/transition_table.rb +33 -41
  51. data/lib/action_dispatch/journey/nodes/node.rb +2 -1
  52. data/lib/action_dispatch/journey/parser.rb +99 -196
  53. data/lib/action_dispatch/journey/route.rb +45 -31
  54. data/lib/action_dispatch/journey/router/utils.rb +9 -15
  55. data/lib/action_dispatch/journey/router.rb +59 -81
  56. data/lib/action_dispatch/journey/routes.rb +7 -0
  57. data/lib/action_dispatch/journey/scanner.rb +44 -42
  58. data/lib/action_dispatch/journey/visitors.rb +55 -23
  59. data/lib/action_dispatch/journey/visualizer/fsm.js +4 -6
  60. data/lib/action_dispatch/log_subscriber.rb +7 -3
  61. data/lib/action_dispatch/middleware/cookies.rb +24 -5
  62. data/lib/action_dispatch/middleware/debug_exceptions.rb +24 -5
  63. data/lib/action_dispatch/middleware/debug_view.rb +11 -5
  64. data/lib/action_dispatch/middleware/exception_wrapper.rb +12 -12
  65. data/lib/action_dispatch/middleware/executor.rb +12 -2
  66. data/lib/action_dispatch/middleware/host_authorization.rb +3 -2
  67. data/lib/action_dispatch/middleware/public_exceptions.rb +1 -5
  68. data/lib/action_dispatch/middleware/remote_ip.rb +61 -24
  69. data/lib/action_dispatch/middleware/request_id.rb +2 -1
  70. data/lib/action_dispatch/middleware/session/abstract_store.rb +5 -0
  71. data/lib/action_dispatch/middleware/session/cache_store.rb +44 -4
  72. data/lib/action_dispatch/middleware/session/cookie_store.rb +0 -3
  73. data/lib/action_dispatch/middleware/ssl.rb +13 -3
  74. data/lib/action_dispatch/middleware/templates/rescues/_copy_button.html.erb +1 -0
  75. data/lib/action_dispatch/middleware/templates/rescues/_source.html.erb +3 -5
  76. data/lib/action_dispatch/middleware/templates/rescues/_trace.html.erb +9 -5
  77. data/lib/action_dispatch/middleware/templates/rescues/blocked_host.html.erb +1 -0
  78. data/lib/action_dispatch/middleware/templates/rescues/diagnostics.html.erb +1 -0
  79. data/lib/action_dispatch/middleware/templates/rescues/invalid_statement.html.erb +4 -0
  80. data/lib/action_dispatch/middleware/templates/rescues/invalid_statement.text.erb +3 -0
  81. data/lib/action_dispatch/middleware/templates/rescues/layout.erb +50 -0
  82. data/lib/action_dispatch/middleware/templates/rescues/missing_exact_template.html.erb +1 -0
  83. data/lib/action_dispatch/middleware/templates/rescues/missing_template.html.erb +1 -0
  84. data/lib/action_dispatch/middleware/templates/rescues/routing_error.html.erb +7 -8
  85. data/lib/action_dispatch/middleware/templates/rescues/routing_error.text.erb +1 -1
  86. data/lib/action_dispatch/middleware/templates/rescues/template_error.html.erb +1 -0
  87. data/lib/action_dispatch/middleware/templates/rescues/unknown_action.html.erb +1 -0
  88. data/lib/action_dispatch/railtie.rb +21 -0
  89. data/lib/action_dispatch/request/session.rb +1 -0
  90. data/lib/action_dispatch/request/utils.rb +9 -3
  91. data/lib/action_dispatch/routing/inspector.rb +80 -57
  92. data/lib/action_dispatch/routing/mapper.rb +404 -223
  93. data/lib/action_dispatch/routing/polymorphic_routes.rb +2 -2
  94. data/lib/action_dispatch/routing/redirection.rb +10 -7
  95. data/lib/action_dispatch/routing/route_set.rb +21 -12
  96. data/lib/action_dispatch/routing/routes_proxy.rb +1 -0
  97. data/lib/action_dispatch/structured_event_subscriber.rb +20 -0
  98. data/lib/action_dispatch/system_test_case.rb +3 -3
  99. data/lib/action_dispatch/system_testing/browser.rb +15 -22
  100. data/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb +2 -2
  101. data/lib/action_dispatch/testing/assertions/response.rb +26 -2
  102. data/lib/action_dispatch/testing/assertions/routing.rb +27 -15
  103. data/lib/action_dispatch/testing/integration.rb +18 -7
  104. data/lib/action_dispatch/testing/test_helpers/page_dump_helper.rb +1 -1
  105. data/lib/action_dispatch.rb +14 -4
  106. data/lib/action_pack/gem_version.rb +3 -3
  107. metadata +18 -48
  108. data/lib/action_dispatch/journey/parser.y +0 -50
  109. data/lib/action_dispatch/journey/parser_extras.rb +0 -33
@@ -10,7 +10,6 @@ require "active_support/deep_mergeable"
10
10
  require "action_dispatch/http/upload"
11
11
  require "rack/test"
12
12
  require "stringio"
13
- require "set"
14
13
  require "yaml"
15
14
 
16
15
  module ActionController
@@ -18,16 +17,18 @@ module ActionController
18
17
  #
19
18
  # params = ActionController::Parameters.new(a: {})
20
19
  # params.fetch(:b)
21
- # # => ActionController::ParameterMissing: param is missing or the value is empty: b
20
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: b
22
21
  # params.require(:a)
23
- # # => ActionController::ParameterMissing: param is missing or the value is empty: a
22
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: a
23
+ # params.expect(a: [])
24
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: a
24
25
  class ParameterMissing < KeyError
25
26
  attr_reader :param, :keys # :nodoc:
26
27
 
27
28
  def initialize(param, keys = nil) # :nodoc:
28
29
  @param = param
29
30
  @keys = keys
30
- super("param is missing or the value is empty: #{param}")
31
+ super("param is missing or the value is empty or invalid: #{param}")
31
32
  end
32
33
 
33
34
  if defined?(DidYouMean::Correctable) && defined?(DidYouMean::SpellChecker)
@@ -39,6 +40,15 @@ module ActionController
39
40
  end
40
41
  end
41
42
 
43
+ # Raised from `expect!` when an expected parameter is missing or is of an
44
+ # incompatible type.
45
+ #
46
+ # params = ActionController::Parameters.new(a: {})
47
+ # params.expect!(:a)
48
+ # # => ActionController::ExpectedParameterMissing: param is missing or the value is empty or invalid: a
49
+ class ExpectedParameterMissing < ParameterMissing
50
+ end
51
+
42
52
  # Raised when a supplied parameter is not expected and
43
53
  # ActionController::Parameters.action_on_unpermitted_parameters is set to
44
54
  # `:raise`.
@@ -78,9 +88,14 @@ module ActionController
78
88
  #
79
89
  # Allows you to choose which attributes should be permitted for mass updating
80
90
  # and thus prevent accidentally exposing that which shouldn't be exposed.
81
- # Provides two methods for this purpose: #require and #permit. The former is
82
- # used to mark parameters as required. The latter is used to set the parameter
83
- # as permitted and limit which attributes should be allowed for mass updating.
91
+ #
92
+ # Provides methods for filtering and requiring params:
93
+ #
94
+ # * `expect` to safely permit and require parameters in one step.
95
+ # * `permit` to filter params for mass assignment.
96
+ # * `require` to require a parameter or raise an error.
97
+ #
98
+ # Examples:
84
99
  #
85
100
  # params = ActionController::Parameters.new({
86
101
  # person: {
@@ -90,14 +105,14 @@ module ActionController
90
105
  # }
91
106
  # })
92
107
  #
93
- # permitted = params.require(:person).permit(:name, :age)
94
- # permitted # => #<ActionController::Parameters {"name"=>"Francesco", "age"=>22} permitted: true>
95
- # permitted.permitted? # => true
108
+ # permitted = params.expect(person: [:name, :age])
109
+ # permitted # => #<ActionController::Parameters {"name"=>"Francesco", "age"=>22} permitted: true>
96
110
  #
97
111
  # Person.first.update!(permitted)
98
112
  # # => #<Person id: 1, name: "Francesco", age: 22, role: "user">
99
113
  #
100
- # It provides two options that controls the top-level behavior of new instances:
114
+ # Parameters provides two options that control the top-level behavior of new
115
+ # instances:
101
116
  #
102
117
  # * `permit_all_parameters` - If it's `true`, all the parameters will be
103
118
  # permitted by default. The default is `false`.
@@ -112,8 +127,6 @@ module ActionController
112
127
  # * `:raise` to raise an ActionController::UnpermittedParameters
113
128
  # exception.
114
129
  #
115
- #
116
- #
117
130
  # Examples:
118
131
  #
119
132
  # params = ActionController::Parameters.new
@@ -132,7 +145,7 @@ module ActionController
132
145
  #
133
146
  # params = ActionController::Parameters.new(a: "123", b: "456")
134
147
  # params.permit(:c)
135
- # # => ActionController::UnpermittedParameters: found unpermitted keys: a, b
148
+ # # => ActionController::UnpermittedParameters: found unpermitted parameters: :a, :b
136
149
  #
137
150
  # Please note that these options *are not thread-safe*. In a multi-threaded
138
151
  # environment they should only be set once at boot-time and never mutated at
@@ -184,15 +197,14 @@ module ActionController
184
197
  # as_json(options=nil)
185
198
  #
186
199
  # Returns a hash that can be used as the JSON representation for the parameters.
187
-
188
- ##
189
- # :method: each_key
190
200
  #
191
- # :call-seq:
192
- # each_key(&block)
201
+ # Like `#to_unsafe_h`, the hash holds every parameter, permitted or not, and
202
+ # mass assignment does not check it. Do not pass it to a model.
193
203
  #
194
- # Calls block once for each key in the parameters, passing the key. If no block
195
- # is given, an enumerator is returned instead.
204
+ # params = ActionController::Parameters.new(name: "Bob", admin: true)
205
+ # params.as_json # => {"name" => "Bob", "admin" => true}
206
+ # User.new(params) # => ActiveModel::ForbiddenAttributesError
207
+ # User.new(params.as_json) # => #<User name: "Bob", admin: true>
196
208
 
197
209
  ##
198
210
  # :method: empty?
@@ -235,7 +247,7 @@ module ActionController
235
247
  # Returns the content of the parameters as a string.
236
248
 
237
249
  delegate :keys, :empty?, :exclude?, :include?,
238
- :as_json, :to_s, :each_key, to: :@parameters
250
+ :as_json, :to_s, to: :@parameters
239
251
 
240
252
  alias_method :has_key?, :include?
241
253
  alias_method :key?, :include?
@@ -250,20 +262,6 @@ module ActionController
250
262
  cattr_accessor :always_permitted_parameters, default: %w( controller action )
251
263
 
252
264
  class << self
253
- def allow_deprecated_parameters_hash_equality
254
- ActionController.deprecator.warn <<-WARNING.squish
255
- `Rails.application.config.action_controller.allow_deprecated_parameters_hash_equality` is
256
- deprecated and will be removed in Rails 8.0.
257
- WARNING
258
- end
259
-
260
- def allow_deprecated_parameters_hash_equality=(value)
261
- ActionController.deprecator.warn <<-WARNING.squish
262
- `Rails.application.config.action_controller.allow_deprecated_parameters_hash_equality`
263
- is deprecated and will be removed in Rails 8.0.
264
- WARNING
265
- end
266
-
267
265
  def nested_attribute?(key, value) # :nodoc:
268
266
  /\A-?\d+\z/.match?(key) && (value.is_a?(Hash) || value.is_a?(Parameters))
269
267
  end
@@ -421,6 +419,15 @@ module ActionController
421
419
  self
422
420
  end
423
421
 
422
+ # Calls block once for each key in the parameters, passing the key. If no block
423
+ # is given, an enumerator is returned instead.
424
+ def each_key(&block)
425
+ return to_enum(:each_key) unless block_given?
426
+ @parameters.each_key(&block)
427
+
428
+ self
429
+ end
430
+
424
431
  # Returns a new array of the values of the parameters.
425
432
  def values
426
433
  to_enum(:each_value).to_a
@@ -481,16 +488,16 @@ module ActionController
481
488
  # Otherwise raises ActionController::ParameterMissing:
482
489
  #
483
490
  # ActionController::Parameters.new.require(:person)
484
- # # ActionController::ParameterMissing: param is missing or the value is empty: person
491
+ # # ActionController::ParameterMissing: param is missing or the value is empty or invalid: person
485
492
  #
486
493
  # ActionController::Parameters.new(person: nil).require(:person)
487
- # # ActionController::ParameterMissing: param is missing or the value is empty: person
494
+ # # ActionController::ParameterMissing: param is missing or the value is empty or invalid: person
488
495
  #
489
496
  # ActionController::Parameters.new(person: "\t").require(:person)
490
- # # ActionController::ParameterMissing: param is missing or the value is empty: person
497
+ # # ActionController::ParameterMissing: param is missing or the value is empty or invalid: person
491
498
  #
492
499
  # ActionController::Parameters.new(person: {}).require(:person)
493
- # # ActionController::ParameterMissing: param is missing or the value is empty: person
500
+ # # ActionController::ParameterMissing: param is missing or the value is empty or invalid: person
494
501
  #
495
502
  # When given an array of keys, the method tries to require each one of them in
496
503
  # order. If it succeeds, an array with the respective return values is returned:
@@ -502,23 +509,21 @@ module ActionController
502
509
  #
503
510
  # params = ActionController::Parameters.new(user: {}, profile: {})
504
511
  # user_params, profile_params = params.require([:user, :profile])
505
- # # ActionController::ParameterMissing: param is missing or the value is empty: user
512
+ # # ActionController::ParameterMissing: param is missing or the value is empty or invalid: user
506
513
  #
507
- # Technically this method can be used to fetch terminal values:
514
+ # This method is not recommended for fetching terminal values because it does
515
+ # not permit the values. For example, this can cause problems:
508
516
  #
509
517
  # # CAREFUL
510
518
  # params = ActionController::Parameters.new(person: { name: "Finn" })
511
519
  # name = params.require(:person).require(:name) # CAREFUL
512
520
  #
513
- # but take into account that at some point those ones have to be permitted:
521
+ # It is recommended to use `expect` instead:
514
522
  #
515
523
  # def person_params
516
- # params.require(:person).permit(:name).tap do |person_params|
517
- # person_params.require(:name) # SAFER
518
- # end
524
+ # params.expect(person: :name).require(:name)
519
525
  # end
520
526
  #
521
- # for example.
522
527
  def require(key)
523
528
  return key.map { |k| require(k) } if key.is_a?(Array)
524
529
  value = self[key]
@@ -536,8 +541,8 @@ module ActionController
536
541
  # This is useful for limiting which attributes should be allowed for mass
537
542
  # updating.
538
543
  #
539
- # params = ActionController::Parameters.new(user: { name: "Francesco", age: 22, role: "admin" })
540
- # permitted = params.require(:user).permit(:name, :age)
544
+ # params = ActionController::Parameters.new(name: "Francesco", age: 22, role: "admin")
545
+ # permitted = params.permit(:name, :age)
541
546
  # permitted.permitted? # => true
542
547
  # permitted.has_key?(:name) # => true
543
548
  # permitted.has_key?(:age) # => true
@@ -567,7 +572,7 @@ module ActionController
567
572
  # `permit` ensures values in the returned structure are permitted scalars and
568
573
  # filters out anything else.
569
574
  #
570
- # You can also use `permit` on nested parameters, like:
575
+ # You can also use `permit` on nested parameters:
571
576
  #
572
577
  # params = ActionController::Parameters.new({
573
578
  # person: {
@@ -587,6 +592,29 @@ module ActionController
587
592
  # permitted[:person][:pets][0][:name] # => "Purplish"
588
593
  # permitted[:person][:pets][0][:category] # => nil
589
594
  #
595
+ # This has the added benefit of rejecting user-modified inputs that send a
596
+ # string when a hash is expected.
597
+ #
598
+ # When followed by `require`, you can both filter and require parameters
599
+ # following the typical pattern of a Rails form. The `expect` method was
600
+ # made specifically for this use case and is the recommended way to require
601
+ # and permit parameters.
602
+ #
603
+ # permitted = params.expect(person: [:name, :age])
604
+ #
605
+ # When using `permit` and `require` separately, pay careful attention to the
606
+ # order of the method calls.
607
+ #
608
+ # params = ActionController::Parameters.new(person: { name: "Martin", age: 40, role: "admin" })
609
+ # permitted = params.permit(person: [:name, :age]).require(:person) # correct
610
+ #
611
+ # When require is used first, it is possible for users of your application to
612
+ # trigger a NoMethodError when the user, for example, sends a string for :person.
613
+ #
614
+ # params = ActionController::Parameters.new(person: "tampered")
615
+ # permitted = params.require(:person).permit(:name, :age) # not recommended
616
+ # # => NoMethodError: undefined method `permit' for an instance of String
617
+ #
590
618
  # Note that if you use `permit` in a key that points to a hash, it won't allow
591
619
  # all the hash. You also need to specify which attributes inside the hash should
592
620
  # be permitted.
@@ -600,13 +628,13 @@ module ActionController
600
628
  # }
601
629
  # })
602
630
  #
603
- # params.require(:person).permit(:contact)
604
- # # => #<ActionController::Parameters {} permitted: true>
631
+ # params.permit(person: :contact).require(:person)
632
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: person
605
633
  #
606
- # params.require(:person).permit(contact: :phone)
634
+ # params.permit(person: { contact: :phone }).require(:person)
607
635
  # # => #<ActionController::Parameters {"contact"=>#<ActionController::Parameters {"phone"=>"555-1234"} permitted: true>} permitted: true>
608
636
  #
609
- # params.require(:person).permit(contact: [ :email, :phone ])
637
+ # params.permit(person: { contact: [ :email, :phone ] }).require(:person)
610
638
  # # => #<ActionController::Parameters {"contact"=>#<ActionController::Parameters {"email"=>"none@test.com", "phone"=>"555-1234"} permitted: true>} permitted: true>
611
639
  #
612
640
  # If your parameters specify multiple parameters indexed by a number, you can
@@ -646,20 +674,127 @@ module ActionController
646
674
  # params.permit(person: { '0': [:email], '1': [:phone]}).to_h
647
675
  # # => {"person"=>{"0"=>{"email"=>"none@test.com"}, "1"=>{"phone"=>"555-6789"}}}
648
676
  def permit(*filters)
649
- params = self.class.new
650
-
651
- filters.flatten.each do |filter|
652
- case filter
653
- when Symbol, String
654
- permitted_scalar_filter(params, filter)
655
- when Hash
656
- hash_filter(params, filter)
657
- end
658
- end
677
+ permit_filters(filters, on_unpermitted: self.class.action_on_unpermitted_parameters, explicit_arrays: false)
678
+ end
659
679
 
660
- unpermitted_parameters!(params) if self.class.action_on_unpermitted_parameters
680
+ # `expect` is the preferred way to require and permit parameters.
681
+ # It is safer than the previous recommendation to call `permit` and `require`
682
+ # in sequence, which could allow user triggered 500 errors.
683
+ #
684
+ # `expect` is more strict with types to avoid a number of potential pitfalls
685
+ # that may be encountered with the `.require.permit` pattern.
686
+ #
687
+ # For example:
688
+ #
689
+ # params = ActionController::Parameters.new(comment: { text: "hello" })
690
+ # params.expect(comment: [:text])
691
+ # # => #<ActionController::Parameters { text: "hello" } permitted: true>
692
+ #
693
+ # params = ActionController::Parameters.new(comment: [{ text: "hello" }, { text: "world" }])
694
+ # params.expect(comment: [:text])
695
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: comment
696
+ #
697
+ # In order to permit an array of parameters, the array must be defined
698
+ # explicitly. Use double array brackets, an array inside an array, to
699
+ # declare that an array of parameters is expected.
700
+ #
701
+ # params = ActionController::Parameters.new(comments: [{ text: "hello" }, { text: "world" }])
702
+ # params.expect(comments: [[:text]])
703
+ # # => [#<ActionController::Parameters { "text" => "hello" } permitted: true>,
704
+ # # #<ActionController::Parameters { "text" => "world" } permitted: true>]
705
+ #
706
+ # params = ActionController::Parameters.new(comments: { text: "hello" })
707
+ # params.expect(comments: [[:text]])
708
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: comments
709
+ #
710
+ # `expect` is intended to protect against array tampering.
711
+ #
712
+ # params = ActionController::Parameters.new(user: "hack")
713
+ # # The previous way of requiring and permitting parameters will error
714
+ # params.require(:user).permit(:name, pets: [:name]) # wrong
715
+ # # => NoMethodError: undefined method `permit' for an instance of String
716
+ #
717
+ # # similarly with nested parameters
718
+ # params = ActionController::Parameters.new(user: { name: "Martin", pets: { name: "hack" } })
719
+ # user_params = params.require(:user).permit(:name, pets: [:name]) # wrong
720
+ # # user_params[:pets] is expected to be an array but is a hash
721
+ #
722
+ # `expect` solves this by being more strict with types.
723
+ #
724
+ # params = ActionController::Parameters.new(user: "hack")
725
+ # params.expect(user: [ :name, pets: [[:name]] ])
726
+ # # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: user
727
+ #
728
+ # # with nested parameters
729
+ # params = ActionController::Parameters.new(user: { name: "Martin", pets: { name: "hack" } })
730
+ # user_params = params.expect(user: [:name, pets: [[:name]] ])
731
+ # user_params[:pets] # => nil
732
+ #
733
+ # As the examples show, `expect` requires the `:user` key, and any root keys
734
+ # similar to the `.require.permit` pattern. If multiple root keys are
735
+ # expected, they will all be required.
736
+ #
737
+ # params = ActionController::Parameters.new(name: "Martin", pies: [{ type: "dessert", flavor: "pumpkin"}])
738
+ # name, pies = params.expect(:name, pies: [[:type, :flavor]])
739
+ # name # => "Martin"
740
+ # pies # => [#<ActionController::Parameters {"type"=>"dessert", "flavor"=>"pumpkin"} permitted: true>]
741
+ #
742
+ # When called with a hash with multiple keys, `expect` will permit the
743
+ # parameters and require the keys in the order they are given in the hash,
744
+ # returning an array of the permitted parameters.
745
+ #
746
+ # params = ActionController::Parameters.new(subject: { name: "Martin" }, object: { pie: "pumpkin" })
747
+ # subject, object = params.expect(subject: [:name], object: [:pie])
748
+ # subject # => #<ActionController::Parameters {"name"=>"Martin"} permitted: true>
749
+ # object # => #<ActionController::Parameters {"pie"=>"pumpkin"} permitted: true>
750
+ #
751
+ # Besides being more strict about array vs hash params, `expect` uses permit
752
+ # internally, so it will behave similarly.
753
+ #
754
+ # params = ActionController::Parameters.new({
755
+ # person: {
756
+ # name: "Francesco",
757
+ # age: 22,
758
+ # pets: [{
759
+ # name: "Purplish",
760
+ # category: "dogs"
761
+ # }]
762
+ # }
763
+ # })
764
+ #
765
+ # permitted = params.expect(person: [ :name, { pets: [[:name]] } ])
766
+ # permitted.permitted? # => true
767
+ # permitted[:name] # => "Francesco"
768
+ # permitted[:age] # => nil
769
+ # permitted[:pets][0][:name] # => "Purplish"
770
+ # permitted[:pets][0][:category] # => nil
771
+ #
772
+ # An array of permitted scalars may be expected with the following:
773
+ #
774
+ # params = ActionController::Parameters.new(tags: ["rails", "parameters"])
775
+ # permitted = params.expect(tags: [])
776
+ # permitted # => ["rails", "parameters"]
777
+ # permitted.is_a?(Array) # => true
778
+ # permitted.size # => 2
779
+ #
780
+ def expect(*filters)
781
+ params = permit_filters(filters)
782
+ keys = filters.flatten.flat_map { |f| f.is_a?(Hash) ? f.keys : f }
783
+ values = params.require(keys)
784
+ values.size == 1 ? values.first : values
785
+ end
661
786
 
662
- params.permit!
787
+ # Same as `expect`, but raises an `ActionController::ExpectedParameterMissing`
788
+ # instead of `ActionController::ParameterMissing`. Unlike `expect` which
789
+ # will render a 400 response, `expect!` will raise an exception that is
790
+ # not handled. This is intended for debugging invalid params for an
791
+ # internal API where incorrectly formatted params would indicate a bug
792
+ # in a client library that should be fixed.
793
+ #
794
+ def expect!(*filters)
795
+ expect(*filters)
796
+ rescue ParameterMissing => e
797
+ raise ExpectedParameterMissing.new(e.param, e.keys)
663
798
  end
664
799
 
665
800
  # Returns a parameter for the given `key`. If not found, returns `nil`.
@@ -686,7 +821,7 @@ module ActionController
686
821
  #
687
822
  # params = ActionController::Parameters.new(person: { name: "Francesco" })
688
823
  # params.fetch(:person) # => #<ActionController::Parameters {"name"=>"Francesco"} permitted: false>
689
- # params.fetch(:none) # => ActionController::ParameterMissing: param is missing or the value is empty: none
824
+ # params.fetch(:none) # => ActionController::ParameterMissing: param is missing or the value is empty or invalid: none
690
825
  # params.fetch(:none, {}) # => #<ActionController::Parameters {} permitted: false>
691
826
  # params.fetch(:none, "Francesco") # => "Francesco"
692
827
  # params.fetch(:none) { "Francesco" } # => "Francesco"
@@ -999,6 +1134,26 @@ module ActionController
999
1134
  hash
1000
1135
  end
1001
1136
 
1137
+ # Filters self and optionally checks for unpermitted keys
1138
+ def permit_filters(filters, on_unpermitted: nil, explicit_arrays: true)
1139
+ params = self.class.new
1140
+
1141
+ filters.flatten.each do |filter|
1142
+ case filter
1143
+ when Symbol, String
1144
+ # Declaration [:name, "age"]
1145
+ permitted_scalar_filter(params, filter)
1146
+ when Hash
1147
+ # Declaration [{ person: ... }]
1148
+ hash_filter(params, filter, on_unpermitted:, explicit_arrays:)
1149
+ end
1150
+ end
1151
+
1152
+ unpermitted_parameters!(params, on_unpermitted:)
1153
+
1154
+ params.permit!
1155
+ end
1156
+
1002
1157
  private
1003
1158
  def new_instance_with_inherited_permitted_status(hash)
1004
1159
  self.class.new(hash, @logging_context).tap do |new_instance|
@@ -1088,23 +1243,45 @@ module ActionController
1088
1243
  end
1089
1244
  end
1090
1245
 
1091
- def each_element(object, filter, &block)
1246
+ # When an array is expected, you must specify an array explicitly
1247
+ # using the following format:
1248
+ #
1249
+ # params.expect(comments: [[:flavor]])
1250
+ #
1251
+ # Which will match only the following array formats:
1252
+ #
1253
+ # { pies: [{ flavor: "rhubarb" }, { flavor: "apple" }] }
1254
+ # { pies: { "0" => { flavor: "key lime" }, "1" => { flavor: "mince" } } }
1255
+ #
1256
+ # When using `permit`, arrays are specified the same way as hashes:
1257
+ #
1258
+ # params.expect(pies: [:flavor])
1259
+ #
1260
+ # In this case, `permit` would also allow matching with a hash (or vice versa):
1261
+ #
1262
+ # { pies: { flavor: "cherry" } }
1263
+ #
1264
+ def array_filter?(filter)
1265
+ filter.is_a?(Array) && filter.size == 1 && filter.first.is_a?(Array)
1266
+ end
1267
+
1268
+ # Called when an explicit array filter is encountered.
1269
+ def each_array_element(object, filter, &block)
1092
1270
  case object
1093
1271
  when Array
1094
1272
  object.grep(Parameters).filter_map(&block)
1095
1273
  when Parameters
1096
1274
  if object.nested_attributes? && !specify_numeric_keys?(filter)
1097
1275
  object.each_nested_attribute(&block)
1098
- else
1099
- yield object
1100
1276
  end
1101
1277
  end
1102
1278
  end
1103
1279
 
1104
- def unpermitted_parameters!(params)
1280
+ def unpermitted_parameters!(params, on_unpermitted: self.class.action_on_unpermitted_parameters)
1281
+ return unless on_unpermitted
1105
1282
  unpermitted_keys = unpermitted_keys(params)
1106
1283
  if unpermitted_keys.any?
1107
- case self.class.action_on_unpermitted_parameters
1284
+ case on_unpermitted
1108
1285
  when :log
1109
1286
  name = "unpermitted_parameters.action_controller"
1110
1287
  ActiveSupport::Notifications.instrument(name, keys: unpermitted_keys, context: @logging_context)
@@ -1171,45 +1348,63 @@ module ActionController
1171
1348
  end
1172
1349
  end
1173
1350
 
1174
- def array_of_permitted_scalars?(value)
1175
- if value.is_a?(Array) && value.all? { |element| permitted_scalar?(element) }
1176
- yield value
1177
- end
1178
- end
1179
-
1180
1351
  def non_scalar?(value)
1181
1352
  value.is_a?(Array) || value.is_a?(Parameters)
1182
1353
  end
1183
1354
 
1184
1355
  EMPTY_ARRAY = [] # :nodoc:
1185
1356
  EMPTY_HASH = {} # :nodoc:
1186
- def hash_filter(params, filter)
1357
+ def hash_filter(params, filter, on_unpermitted: self.class.action_on_unpermitted_parameters, explicit_arrays: false)
1187
1358
  filter = filter.with_indifferent_access
1188
1359
 
1189
1360
  # Slicing filters out non-declared keys.
1190
1361
  slice(*filter.keys).each do |key, value|
1191
1362
  next unless value
1192
1363
  next unless has_key? key
1364
+ result = permit_value(value, filter[key], on_unpermitted:, explicit_arrays:)
1365
+ params[key] = result unless result.nil?
1366
+ end
1367
+ end
1193
1368
 
1194
- if filter[key] == EMPTY_ARRAY
1195
- # Declaration { comment_ids: [] }.
1196
- array_of_permitted_scalars?(self[key]) do |val|
1197
- params[key] = val
1198
- end
1199
- elsif filter[key] == EMPTY_HASH
1200
- # Declaration { preferences: {} }.
1201
- if value.is_a?(Parameters)
1202
- params[key] = permit_any_in_parameters(value)
1203
- end
1204
- elsif non_scalar?(value)
1205
- # Declaration { user: :name } or { user: [:name, :age, { address: ... }] }.
1206
- params[key] = each_element(value, filter[key]) do |element|
1207
- element.permit(*Array.wrap(filter[key]))
1208
- end
1209
- end
1369
+ def permit_value(value, filter, on_unpermitted:, explicit_arrays:)
1370
+ if filter == EMPTY_ARRAY # Declaration { comment_ids: [] }.
1371
+ permit_array_of_scalars(value)
1372
+ elsif filter == EMPTY_HASH # Declaration { preferences: {} }.
1373
+ permit_hash(value, filter, on_unpermitted:, explicit_arrays:)
1374
+ elsif array_filter?(filter) # Declaration { comments: [[:text]] }
1375
+ permit_array_of_hashes(value, filter.first, on_unpermitted:, explicit_arrays:)
1376
+ elsif explicit_arrays # Declaration { user: { address: ... } } or { user: [:name, ...] } (only allows hash value)
1377
+ permit_hash(value, filter, on_unpermitted:, explicit_arrays:)
1378
+ elsif non_scalar?(value) # Declaration { user: { address: ... } } or { user: [:name, ...] }
1379
+ permit_hash_or_array(value, filter, on_unpermitted:, explicit_arrays:)
1210
1380
  end
1211
1381
  end
1212
1382
 
1383
+ def permit_array_of_scalars(value)
1384
+ value if value.is_a?(Array) && value.all? { |element| permitted_scalar?(element) }
1385
+ end
1386
+
1387
+ def permit_array_of_hashes(value, filter, on_unpermitted:, explicit_arrays:)
1388
+ each_array_element(value, filter) do |element|
1389
+ element.permit_filters(Array.wrap(filter), on_unpermitted:, explicit_arrays:)
1390
+ end
1391
+ end
1392
+
1393
+ def permit_hash(value, filter, on_unpermitted:, explicit_arrays:)
1394
+ return unless value.is_a?(Parameters)
1395
+
1396
+ if filter == EMPTY_HASH
1397
+ permit_any_in_parameters(value)
1398
+ else
1399
+ value.permit_filters(Array.wrap(filter), on_unpermitted:, explicit_arrays:)
1400
+ end
1401
+ end
1402
+
1403
+ def permit_hash_or_array(value, filter, on_unpermitted:, explicit_arrays:)
1404
+ permit_array_of_hashes(value, filter, on_unpermitted:, explicit_arrays:) ||
1405
+ permit_hash(value, filter, on_unpermitted:, explicit_arrays:)
1406
+ end
1407
+
1213
1408
  def permit_any_in_parameters(params)
1214
1409
  self.class.new.tap do |sanitized|
1215
1410
  params.each do |key, value|
@@ -1284,7 +1479,7 @@ module ActionController
1284
1479
  # # list between create and update. Also, you can specialize this method
1285
1480
  # # with per-user checking of permissible attributes.
1286
1481
  # def person_params
1287
- # params.require(:person).permit(:name, :age)
1482
+ # params.expect(person: [:name, :age])
1288
1483
  # end
1289
1484
  # end
1290
1485
  #
@@ -1311,11 +1506,12 @@ module ActionController
1311
1506
  # # It's mandatory to specify the nested attributes that should be permitted.
1312
1507
  # # If you use `permit` with just the key that points to the nested attributes hash,
1313
1508
  # # it will return an empty hash.
1314
- # params.require(:person).permit(:name, :age, pets_attributes: [ :id, :name, :category ])
1509
+ # params.expect(person: [ :name, :age, pets_attributes: [ :id, :name, :category ] ])
1315
1510
  # end
1316
1511
  # end
1317
1512
  #
1318
- # See ActionController::Parameters.require and
1513
+ # See ActionController::Parameters.expect,
1514
+ # See ActionController::Parameters.require, and
1319
1515
  # ActionController::Parameters.permit for more information.
1320
1516
  module StrongParameters
1321
1517
  # Returns a new ActionController::Parameters object that has been instantiated