grape 0.5.0 → 3.2.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 (215) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +1223 -164
  3. data/CONTRIBUTING.md +148 -0
  4. data/LICENSE +1 -1
  5. data/README.md +3531 -675
  6. data/UPGRADING.md +1851 -0
  7. data/grape.gemspec +26 -32
  8. data/grape.png +0 -0
  9. data/lib/grape/api/instance.rb +194 -0
  10. data/lib/grape/api.rb +110 -485
  11. data/lib/grape/content_types.rb +28 -0
  12. data/lib/grape/cookies.rb +32 -25
  13. data/lib/grape/declared_params_handler.rb +118 -0
  14. data/lib/grape/dry_types.rb +54 -0
  15. data/lib/grape/dsl/callbacks.rb +19 -0
  16. data/lib/grape/dsl/declared.rb +35 -0
  17. data/lib/grape/dsl/desc.rb +65 -0
  18. data/lib/grape/dsl/headers.rb +21 -0
  19. data/lib/grape/dsl/helpers.rb +103 -0
  20. data/lib/grape/dsl/inside_route.rb +293 -0
  21. data/lib/grape/dsl/logger.rb +19 -0
  22. data/lib/grape/dsl/middleware.rb +36 -0
  23. data/lib/grape/dsl/parameters.rb +239 -0
  24. data/lib/grape/dsl/request_response.rb +168 -0
  25. data/lib/grape/dsl/routing.rb +288 -0
  26. data/lib/grape/dsl/settings.rb +67 -0
  27. data/lib/grape/dsl/validations.rb +51 -0
  28. data/lib/grape/endpoint.rb +287 -386
  29. data/lib/grape/env.rb +20 -0
  30. data/lib/grape/error_formatter/base.rb +56 -19
  31. data/lib/grape/error_formatter/json.rb +18 -7
  32. data/lib/grape/error_formatter/serializable_hash.rb +7 -0
  33. data/lib/grape/error_formatter/txt.rb +14 -11
  34. data/lib/grape/error_formatter/xml.rb +5 -11
  35. data/lib/grape/error_formatter.rb +15 -0
  36. data/lib/grape/exceptions/base.rb +31 -47
  37. data/lib/grape/exceptions/incompatible_option_values.rb +11 -0
  38. data/lib/grape/exceptions/invalid_accept_header.rb +11 -0
  39. data/lib/grape/exceptions/invalid_formatter.rb +3 -5
  40. data/lib/grape/exceptions/invalid_message_body.rb +11 -0
  41. data/lib/grape/exceptions/invalid_response.rb +11 -0
  42. data/lib/grape/exceptions/invalid_version_header.rb +11 -0
  43. data/lib/grape/exceptions/invalid_versioner_option.rb +3 -6
  44. data/lib/grape/exceptions/invalid_with_option_for_represent.rb +3 -7
  45. data/lib/grape/exceptions/method_not_allowed.rb +11 -0
  46. data/lib/grape/exceptions/missing_group_type.rb +11 -0
  47. data/lib/grape/exceptions/missing_mime_type.rb +3 -6
  48. data/lib/grape/exceptions/missing_vendor_option.rb +3 -5
  49. data/lib/grape/exceptions/request_error.rb +11 -0
  50. data/lib/grape/exceptions/unknown_auth_strategy.rb +11 -0
  51. data/lib/grape/exceptions/unknown_parameter.rb +11 -0
  52. data/lib/grape/exceptions/unknown_params_builder.rb +11 -0
  53. data/lib/grape/exceptions/unknown_validator.rb +3 -4
  54. data/lib/grape/exceptions/unsupported_group_type.rb +11 -0
  55. data/lib/grape/exceptions/validation.rb +20 -8
  56. data/lib/grape/exceptions/validation_array_errors.rb +14 -0
  57. data/lib/grape/exceptions/validation_errors.rb +59 -0
  58. data/lib/grape/formatter/base.rb +9 -26
  59. data/lib/grape/formatter/json.rb +6 -7
  60. data/lib/grape/formatter/serializable_hash.rb +24 -20
  61. data/lib/grape/formatter/txt.rb +5 -7
  62. data/lib/grape/formatter/xml.rb +6 -7
  63. data/lib/grape/formatter.rb +17 -0
  64. data/lib/grape/json.rb +10 -0
  65. data/lib/grape/locale/en.yml +47 -20
  66. data/lib/grape/middleware/auth/base.rb +25 -0
  67. data/lib/grape/middleware/auth/dsl.rb +38 -0
  68. data/lib/grape/middleware/auth/strategies.rb +25 -0
  69. data/lib/grape/middleware/auth/strategy_info.rb +15 -0
  70. data/lib/grape/middleware/base.rb +73 -19
  71. data/lib/grape/middleware/error.rb +104 -44
  72. data/lib/grape/middleware/filter.rb +5 -3
  73. data/lib/grape/middleware/formatter.rb +115 -105
  74. data/lib/grape/middleware/globals.rb +14 -0
  75. data/lib/grape/middleware/stack.rb +110 -0
  76. data/lib/grape/middleware/versioner/accept_version_header.rb +11 -40
  77. data/lib/grape/middleware/versioner/base.rb +76 -0
  78. data/lib/grape/middleware/versioner/header.rb +61 -78
  79. data/lib/grape/middleware/versioner/param.rb +9 -21
  80. data/lib/grape/middleware/versioner/path.rb +16 -31
  81. data/lib/grape/middleware/versioner.rb +10 -15
  82. data/lib/grape/namespace.rb +39 -10
  83. data/lib/grape/params_builder/base.rb +20 -0
  84. data/lib/grape/params_builder/hash.rb +11 -0
  85. data/lib/grape/params_builder/hash_with_indifferent_access.rb +11 -0
  86. data/lib/grape/params_builder/hashie_mash.rb +11 -0
  87. data/lib/grape/params_builder.rb +15 -0
  88. data/lib/grape/parser/base.rb +9 -24
  89. data/lib/grape/parser/json.rb +8 -7
  90. data/lib/grape/parser/xml.rb +8 -7
  91. data/lib/grape/parser.rb +15 -0
  92. data/lib/grape/path.rb +76 -0
  93. data/lib/grape/presenters/presenter.rb +11 -0
  94. data/lib/grape/railtie.rb +9 -0
  95. data/lib/grape/request.rb +182 -0
  96. data/lib/grape/router/base_route.rb +48 -0
  97. data/lib/grape/router/greedy_route.rb +26 -0
  98. data/lib/grape/router/pattern.rb +67 -0
  99. data/lib/grape/router/route.rb +58 -0
  100. data/lib/grape/router.rb +167 -0
  101. data/lib/grape/serve_stream/file_body.rb +36 -0
  102. data/lib/grape/serve_stream/sendfile_response.rb +21 -0
  103. data/lib/grape/serve_stream/stream_response.rb +23 -0
  104. data/lib/grape/util/api_description.rb +58 -0
  105. data/lib/grape/util/base_inheritable.rb +46 -0
  106. data/lib/grape/util/cache.rb +18 -0
  107. data/lib/grape/util/deep_freeze.rb +35 -0
  108. data/lib/grape/util/endpoint_configuration.rb +8 -0
  109. data/lib/grape/util/header.rb +13 -0
  110. data/lib/grape/util/inheritable_setting.rb +107 -0
  111. data/lib/grape/util/inheritable_values.rb +29 -0
  112. data/lib/grape/util/lazy/block.rb +29 -0
  113. data/lib/grape/util/lazy/value.rb +38 -0
  114. data/lib/grape/util/lazy/value_array.rb +21 -0
  115. data/lib/grape/util/lazy/value_enumerable.rb +34 -0
  116. data/lib/grape/util/lazy/value_hash.rb +21 -0
  117. data/lib/grape/util/media_type.rb +70 -0
  118. data/lib/grape/util/registry.rb +27 -0
  119. data/lib/grape/util/reverse_stackable_values.rb +15 -0
  120. data/lib/grape/util/stackable_values.rb +36 -0
  121. data/lib/grape/util/translation.rb +42 -0
  122. data/lib/grape/validations/attributes_iterator.rb +77 -0
  123. data/lib/grape/validations/contract_scope.rb +28 -0
  124. data/lib/grape/validations/multiple_attributes_iterator.rb +13 -0
  125. data/lib/grape/validations/param_scope_tracker.rb +57 -0
  126. data/lib/grape/validations/params_documentation.rb +50 -0
  127. data/lib/grape/validations/params_scope.rb +529 -0
  128. data/lib/grape/validations/single_attribute_iterator.rb +26 -0
  129. data/lib/grape/validations/types/array_coercer.rb +60 -0
  130. data/lib/grape/validations/types/custom_type_coercer.rb +164 -0
  131. data/lib/grape/validations/types/custom_type_collection_coercer.rb +56 -0
  132. data/lib/grape/validations/types/dry_type_coercer.rb +59 -0
  133. data/lib/grape/validations/types/file.rb +31 -0
  134. data/lib/grape/validations/types/invalid_value.rb +17 -0
  135. data/lib/grape/validations/types/json.rb +71 -0
  136. data/lib/grape/validations/types/multiple_type_coercer.rb +57 -0
  137. data/lib/grape/validations/types/primitive_coercer.rb +46 -0
  138. data/lib/grape/validations/types/set_coercer.rb +35 -0
  139. data/lib/grape/validations/types/variant_collection_coercer.rb +51 -0
  140. data/lib/grape/validations/types.rb +198 -0
  141. data/lib/grape/validations/validators/all_or_none_of_validator.rb +19 -0
  142. data/lib/grape/validations/validators/allow_blank_validator.rb +25 -0
  143. data/lib/grape/validations/validators/as_validator.rb +14 -0
  144. data/lib/grape/validations/validators/at_least_one_of_validator.rb +18 -0
  145. data/lib/grape/validations/validators/base.rb +158 -0
  146. data/lib/grape/validations/validators/coerce_validator.rb +55 -0
  147. data/lib/grape/validations/validators/contract_scope_validator.rb +45 -0
  148. data/lib/grape/validations/validators/default_validator.rb +31 -0
  149. data/lib/grape/validations/validators/exactly_one_of_validator.rb +24 -0
  150. data/lib/grape/validations/validators/except_values_validator.rb +33 -0
  151. data/lib/grape/validations/validators/length_validator.rb +48 -0
  152. data/lib/grape/validations/validators/multiple_params_base.rb +34 -0
  153. data/lib/grape/validations/validators/mutually_exclusive_validator.rb +18 -0
  154. data/lib/grape/validations/validators/presence_validator.rb +17 -0
  155. data/lib/grape/validations/validators/regexp_validator.rb +24 -0
  156. data/lib/grape/validations/validators/same_as_validator.rb +20 -0
  157. data/lib/grape/validations/validators/values_validator.rb +68 -0
  158. data/lib/grape/validations.rb +10 -226
  159. data/lib/grape/version.rb +4 -1
  160. data/lib/grape/xml.rb +10 -0
  161. data/lib/grape.rb +79 -77
  162. metadata +160 -306
  163. data/.gitignore +0 -38
  164. data/.rspec +0 -2
  165. data/.travis.yml +0 -9
  166. data/.yardopts +0 -2
  167. data/Gemfile +0 -19
  168. data/Guardfile +0 -15
  169. data/Rakefile +0 -64
  170. data/lib/grape/exceptions/missing_option.rb +0 -13
  171. data/lib/grape/exceptions/unknown_options.rb +0 -14
  172. data/lib/grape/http/request.rb +0 -28
  173. data/lib/grape/middleware/auth/basic.rb +0 -30
  174. data/lib/grape/middleware/auth/digest.rb +0 -30
  175. data/lib/grape/middleware/auth/oauth2.rb +0 -72
  176. data/lib/grape/route.rb +0 -23
  177. data/lib/grape/util/content_types.rb +0 -17
  178. data/lib/grape/util/deep_merge.rb +0 -23
  179. data/lib/grape/util/hash_stack.rb +0 -120
  180. data/lib/grape/validations/coerce.rb +0 -62
  181. data/lib/grape/validations/default.rb +0 -24
  182. data/lib/grape/validations/presence.rb +0 -12
  183. data/lib/grape/validations/regexp.rb +0 -14
  184. data/spec/grape/api_spec.rb +0 -2129
  185. data/spec/grape/endpoint_spec.rb +0 -605
  186. data/spec/grape/entity_spec.rb +0 -281
  187. data/spec/grape/exceptions/invalid_formatter_spec.rb +0 -18
  188. data/spec/grape/exceptions/invalid_versioner_option_spec.rb +0 -18
  189. data/spec/grape/exceptions/missing_mime_type_spec.rb +0 -24
  190. data/spec/grape/exceptions/missing_option_spec.rb +0 -18
  191. data/spec/grape/exceptions/unknown_options_spec.rb +0 -18
  192. data/spec/grape/exceptions/unknown_validator_spec.rb +0 -18
  193. data/spec/grape/middleware/auth/basic_spec.rb +0 -31
  194. data/spec/grape/middleware/auth/digest_spec.rb +0 -47
  195. data/spec/grape/middleware/auth/oauth2_spec.rb +0 -90
  196. data/spec/grape/middleware/base_spec.rb +0 -63
  197. data/spec/grape/middleware/error_spec.rb +0 -49
  198. data/spec/grape/middleware/exception_spec.rb +0 -164
  199. data/spec/grape/middleware/formatter_spec.rb +0 -244
  200. data/spec/grape/middleware/versioner/accept_version_header_spec.rb +0 -121
  201. data/spec/grape/middleware/versioner/header_spec.rb +0 -277
  202. data/spec/grape/middleware/versioner/param_spec.rb +0 -58
  203. data/spec/grape/middleware/versioner/path_spec.rb +0 -44
  204. data/spec/grape/middleware/versioner_spec.rb +0 -22
  205. data/spec/grape/util/hash_stack_spec.rb +0 -133
  206. data/spec/grape/validations/coerce_spec.rb +0 -143
  207. data/spec/grape/validations/default_spec.rb +0 -67
  208. data/spec/grape/validations/presence_spec.rb +0 -144
  209. data/spec/grape/validations/regexp_spec.rb +0 -33
  210. data/spec/grape/validations/zh-CN.yml +0 -9
  211. data/spec/grape/validations_spec.rb +0 -217
  212. data/spec/shared/versioning_examples.rb +0 -121
  213. data/spec/spec_helper.rb +0 -25
  214. data/spec/support/basic_auth_encode_helpers.rb +0 -4
  215. data/spec/support/versioned_helpers.rb +0 -48
@@ -0,0 +1,529 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module Validations
5
+ class ParamsScope
6
+ attr_reader :parent, :type, :nearest_array_ancestor, :full_path
7
+
8
+ def qualifying_params
9
+ ParamScopeTracker.current&.qualifying_params(self)
10
+ end
11
+
12
+ include Grape::DSL::Parameters
13
+ include Grape::Validations::ParamsDocumentation
14
+
15
+ # There are a number of documentation options on entities that don't have
16
+ # corresponding validators. Since there is nowhere that enumerates them all,
17
+ # we maintain a list of them here and skip looking up validators for them.
18
+ RESERVED_DOCUMENTATION_KEYWORDS = %i[as required param_type is_array format example].freeze
19
+
20
+ SPECIAL_JSON = [JSON, Array[JSON]].freeze
21
+
22
+ class Attr
23
+ attr_reader :key, :scope
24
+
25
+ # Open up a new ParamsScope::Attr
26
+ # @param key [Hash, Symbol] key of attr
27
+ # @param scope [Grape::Validations::ParamsScope] scope of attr
28
+ def initialize(key, scope)
29
+ @key = key
30
+ @scope = scope
31
+ end
32
+
33
+ # @return Array[Symbol, Hash[Symbol => Array]] declared_params with symbol instead of Attr
34
+ def self.attrs_keys(declared_params)
35
+ declared_params.map do |declared_param_attr|
36
+ attr_key(declared_param_attr)
37
+ end
38
+ end
39
+
40
+ def self.attr_key(declared_param_attr)
41
+ return attr_key(declared_param_attr.key) if declared_param_attr.is_a?(self)
42
+
43
+ if declared_param_attr.is_a?(Hash)
44
+ declared_param_attr.transform_values { |value| attrs_keys(value) }
45
+ else
46
+ declared_param_attr
47
+ end
48
+ end
49
+ end
50
+
51
+ # Open up a new ParamsScope, allowing parameter definitions per
52
+ # Grape::DSL::Params.
53
+ # @param api [API] the API endpoint to modify
54
+ # @param element [Symbol] the element that contains this scope; for
55
+ # this to be relevant, parent must be set
56
+ # @param element_renamed [Symbol, nil] whenever this scope should
57
+ # be renamed and to what, given +nil+ no renaming is done
58
+ # @param parent [ParamsScope] the scope containing this scope
59
+ # @param optional [Boolean] whether or not this scope needs to have
60
+ # any parameters set or not
61
+ # @param type [Class] a type meant to govern this scope (deprecated)
62
+ # @param type [Hash] group options for this scope
63
+ # @param dependent_on [Symbol] if present, this scope should only
64
+ # validate if this param is present in the parent scope
65
+ # @yield the instance context, open for parameter definitions
66
+ def initialize(api:, element: nil, element_renamed: nil, parent: nil, optional: false, type: nil, group: nil, dependent_on: nil, &block)
67
+ @element = element
68
+ @element_renamed = element_renamed
69
+ @parent = parent
70
+ @api = api
71
+ @optional = optional
72
+ @type = type
73
+ @group = group
74
+ @dependent_on = dependent_on
75
+ # Must be an ivar: push_declared_params is dispatched on self during
76
+ # instance_eval, so local variables from initialize are unreachable.
77
+ # configure_declared_params consumes it and clears @declared_params to nil.
78
+ @declared_params = []
79
+ @full_path = build_full_path
80
+
81
+ instance_eval(&block) if block
82
+
83
+ configure_declared_params
84
+ @nearest_array_ancestor = find_nearest_array_ancestor
85
+ freeze
86
+ end
87
+
88
+ def configuration
89
+ (@api.configuration.respond_to?(:evaluate) && @api.configuration.evaluate) || @api.configuration
90
+ end
91
+
92
+ # @return [Boolean] whether or not this entire scope needs to be
93
+ # validated
94
+ def should_validate?(parameters)
95
+ scoped_params = params(parameters)
96
+
97
+ return false if @optional && (scoped_params.blank? || all_element_blank?(scoped_params))
98
+ return false unless meets_dependency?(scoped_params, parameters)
99
+ return true if @parent.nil?
100
+
101
+ @parent.should_validate?(parameters)
102
+ end
103
+
104
+ def meets_dependency?(params, request_params)
105
+ return true unless @dependent_on
106
+ return false if @parent.present? && !@parent.meets_dependency?(@parent.params(request_params), request_params)
107
+
108
+ if params.is_a?(Array)
109
+ filtered = params.flatten.filter { |param| meets_dependency?(param, request_params) }
110
+ ParamScopeTracker.current&.store_qualifying_params(self, filtered)
111
+ return filtered.present?
112
+ end
113
+
114
+ meets_hash_dependency?(params)
115
+ end
116
+
117
+ def attr_meets_dependency?(params)
118
+ return true unless @dependent_on
119
+ return false if @parent.present? && !@parent.attr_meets_dependency?(params)
120
+
121
+ meets_hash_dependency?(params)
122
+ end
123
+
124
+ def meets_hash_dependency?(params)
125
+ # params might be anything what looks like a hash, so it must implement a `key?` method
126
+ return false unless params.respond_to?(:key?)
127
+
128
+ @dependent_on.all? do |dependency|
129
+ if dependency.is_a?(Hash)
130
+ key, callable = dependency.first
131
+ callable.call(params[key])
132
+ else
133
+ params[dependency].present?
134
+ end
135
+ end
136
+ end
137
+
138
+ # @return [String] the proper attribute name, with nesting considered.
139
+ def full_name(name, index: nil)
140
+ tracker = ParamScopeTracker.current
141
+ if nested?
142
+ # Find our containing element's name, and append ours.
143
+ resolved_index = index || tracker&.index_for(self)
144
+ "#{@parent.full_name(@element)}#{brackets(resolved_index)}#{brackets(name)}"
145
+ elsif lateral?
146
+ # Find the name of the element as if it was at the same nesting level
147
+ # as our parent. We need to forward our index upward to achieve this.
148
+ @parent.full_name(name, index: tracker&.index_for(self))
149
+ else
150
+ # We must be the root scope, so no prefix needed.
151
+ name.to_s
152
+ end
153
+ end
154
+
155
+ def brackets(val)
156
+ "[#{val}]" if val
157
+ end
158
+
159
+ # @return [Boolean] whether or not this scope is the root-level scope
160
+ def root?
161
+ !@parent
162
+ end
163
+
164
+ # A nested scope is contained in one of its parent's elements.
165
+ # @return [Boolean] whether or not this scope is nested
166
+ def nested?
167
+ @parent && @element
168
+ end
169
+
170
+ # A lateral scope is subordinate to its parent, but its keys are at the
171
+ # same level as its parent and thus is not contained within an element.
172
+ # @return [Boolean] whether or not this scope is lateral
173
+ def lateral?
174
+ @parent && !@element
175
+ end
176
+
177
+ # @return [Boolean] whether or not this scope needs to be present, or can
178
+ # be blank
179
+ def required?
180
+ !@optional
181
+ end
182
+
183
+ protected
184
+
185
+ # Adds a parameter declaration to our list of validations.
186
+ # @param attrs [Array] (see Grape::DSL::Parameters#requires)
187
+ def push_declared_params(attrs, **opts)
188
+ opts[:declared_params_scope] = self unless opts.key?(:declared_params_scope)
189
+ return @parent.push_declared_params(attrs, **opts) if lateral?
190
+
191
+ push_renamed_param(full_path + [attrs.first], opts[:as]) if opts[:as]
192
+ @declared_params.concat(attrs.map { |attr| ::Grape::Validations::ParamsScope::Attr.new(attr, opts[:declared_params_scope]) })
193
+ end
194
+
195
+ private
196
+
197
+ def build_full_path
198
+ if nested?
199
+ @parent.full_path + [@element]
200
+ elsif lateral?
201
+ @parent.full_path
202
+ else
203
+ []
204
+ end
205
+ end
206
+
207
+ # Add a new parameter which should be renamed when using the +#declared+
208
+ # method.
209
+ #
210
+ # @param path [Array<String, Symbol>] the full path of the parameter
211
+ # (including the parameter name as last array element)
212
+ # @param new_name [String, Symbol] the new name of the parameter (the
213
+ # renamed name, with the +as: ...+ semantic)
214
+ def push_renamed_param(path, new_name)
215
+ api_route_setting = @api.inheritable_setting.route
216
+ base = api_route_setting[:renamed_params] || {}
217
+ base[Array(path).map(&:to_s)] = new_name.to_s
218
+ api_route_setting[:renamed_params] = base
219
+ end
220
+
221
+ def require_required_and_optional_fields(context, using:, except: nil)
222
+ except_fields = Array.wrap(except)
223
+ using_fields = using.keys.delete_if { |f| except_fields.include?(f) }
224
+
225
+ if context == :all
226
+ optional_fields = except_fields
227
+ required_fields = using_fields
228
+ else # context == :none
229
+ required_fields = except_fields
230
+ optional_fields = using_fields
231
+ end
232
+ required_fields.each do |field|
233
+ field_opts = using[field]
234
+ raise ArgumentError, "required field not exist: #{field}" unless field_opts
235
+
236
+ requires(field, **field_opts)
237
+ end
238
+ optional_fields.each do |field|
239
+ field_opts = using[field]
240
+ optional(field, **field_opts) if field_opts
241
+ end
242
+ end
243
+
244
+ def require_optional_fields(context, using:, except: nil)
245
+ optional_fields = using.keys
246
+ unless context == :all
247
+ except_fields = Array.wrap(except)
248
+ optional_fields.delete_if { |f| except_fields.include?(f) }
249
+ end
250
+ optional_fields.each do |field|
251
+ field_opts = using[field]
252
+ optional(field, **field_opts) if field_opts
253
+ end
254
+ end
255
+
256
+ def validate_attributes(attrs, **opts, &block)
257
+ opts[:type] ||= Array if block
258
+ validates(attrs, opts)
259
+ end
260
+
261
+ # Returns a new parameter scope, subordinate to the current one and nested
262
+ # under the given element.
263
+ # @param element [Symbol] the parameter name under which this scope is nested
264
+ # @param type [Class] the type governing this scope
265
+ # @param as [Symbol, nil] optional renamed name for the element
266
+ # @param optional [Boolean] whether the parameter this scope is nested under
267
+ # is optional or not (and hence, whether this block's params will be).
268
+ # @yield parameter scope
269
+ def new_scope(element, type:, as:, optional: false, &)
270
+ # if required params are grouped and no type or unsupported type is provided, raise an error
271
+ if element && !optional
272
+ raise Grape::Exceptions::MissingGroupType if type.nil?
273
+ raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
274
+ end
275
+
276
+ self.class.new(
277
+ api: @api,
278
+ element:,
279
+ element_renamed: as,
280
+ parent: self,
281
+ optional:,
282
+ type: type || Array,
283
+ group: @group,
284
+ &
285
+ )
286
+ end
287
+
288
+ # Returns a new parameter scope, not nested under any current-level param
289
+ # but instead at the same level as the current scope.
290
+ # @param dependent_on [Symbol] if given, specifies that this scope should
291
+ # only validate if this parameter from the above scope is present
292
+ # @yield parameter scope
293
+ def new_lateral_scope(dependent_on:, &)
294
+ self.class.new(
295
+ api: @api,
296
+ parent: self,
297
+ optional: @optional,
298
+ type: type == Array ? Array : Hash,
299
+ dependent_on:,
300
+ &
301
+ )
302
+ end
303
+
304
+ # Returns a new parameter scope, subordinate to the current one, sharing
305
+ # the given group options with all parameters defined within.
306
+ # @param group [Hash] common options to merge into each parameter in the scope
307
+ # @yield parameter scope
308
+ def new_group_scope(group, &)
309
+ self.class.new(api: @api, parent: self, group:, &)
310
+ end
311
+
312
+ # Pushes declared params to parent or settings, then clears @declared_params.
313
+ # Clearing here (rather than in initialize) keeps the lifecycle ownership in
314
+ # one place: this method both consumes and invalidates the ivar so that
315
+ # push_declared_params cannot be called on the frozen scope later.
316
+ def configure_declared_params
317
+ push_renamed_param(full_path, @element_renamed) if @element_renamed
318
+
319
+ if nested?
320
+ @parent.push_declared_params [@element => @declared_params]
321
+ else
322
+ @api.inheritable_setting.namespace_stackable[:declared_params] = @declared_params
323
+ end
324
+ ensure
325
+ @declared_params = nil
326
+ end
327
+
328
+ def find_nearest_array_ancestor
329
+ scope = @parent
330
+ scope = scope.parent while scope && scope.type != Array
331
+ scope
332
+ end
333
+
334
+ def validates(attrs, validations)
335
+ coerce_type = infer_coercion(validations)
336
+ required = validations.key?(:presence)
337
+ default = validations[:default]
338
+ values = validations[:values].is_a?(Hash) ? validations.dig(:values, :value) : validations[:values]
339
+ except_values = validations[:except_values].is_a?(Hash) ? validations.dig(:except_values, :value) : validations[:except_values]
340
+
341
+ # NB. values and excepts should be nil, Proc, Array, or Range.
342
+ # Specifically, values should NOT be a Hash
343
+ # use values or excepts to guess coerce type when stated type is Array
344
+ coerce_type = guess_coerce_type(coerce_type, values, except_values)
345
+
346
+ # default value should be present in values array, if both exist and are not procs
347
+ check_incompatible_option_values(default, values, except_values)
348
+
349
+ # type should be compatible with values array, if both exist
350
+ validate_value_coercion(coerce_type, values, except_values)
351
+
352
+ document_params attrs, validations, coerce_type, values, except_values
353
+
354
+ opts = derive_validator_options(validations).freeze
355
+
356
+ # Validate for presence before any other validators
357
+ validates_presence(validations, attrs, opts)
358
+
359
+ # Before we run the rest of the validators, let's handle
360
+ # whatever coercion so that we are working with correctly
361
+ # type casted values
362
+ coerce_type validations.extract!(:coerce, :coerce_with, :coerce_message), attrs, required, opts
363
+
364
+ validations.each do |type, options|
365
+ # Don't try to look up validators for documentation params that don't have one.
366
+ next if RESERVED_DOCUMENTATION_KEYWORDS.include?(type)
367
+
368
+ validate(type, options, attrs, required, opts)
369
+ end
370
+ end
371
+
372
+ # Validate and comprehend the +:type+, +:types+, and +:coerce_with+
373
+ # options that have been supplied to the parameter declaration.
374
+ # The +:type+ and +:types+ options will be removed from the
375
+ # validations list, replaced appropriately with +:coerce+ and
376
+ # +:coerce_with+ options that will later be passed to
377
+ # {Validators::CoerceValidator}. The type that is returned may be
378
+ # used for documentation and further validation of parameter
379
+ # options.
380
+ #
381
+ # @param validations [Hash] list of validations supplied to the
382
+ # parameter declaration
383
+ # @return [class-like] type to which the parameter will be coerced
384
+ # @raise [ArgumentError] if the given type options are invalid
385
+ def infer_coercion(validations)
386
+ raise ArgumentError, ':type may not be supplied with :types' if validations.key?(:type) && validations.key?(:types)
387
+
388
+ validations[:coerce] = (options_key?(:type, :value, validations) ? validations[:type][:value] : validations[:type]) if validations.key?(:type)
389
+ validations[:coerce_message] = (options_key?(:type, :message, validations) ? validations[:type][:message] : nil) if validations.key?(:type)
390
+ validations[:coerce] = (options_key?(:types, :value, validations) ? validations[:types][:value] : validations[:types]) if validations.key?(:types)
391
+ validations[:coerce_message] = (options_key?(:types, :message, validations) ? validations[:types][:message] : nil) if validations.key?(:types)
392
+
393
+ validations.delete(:types) if validations.key?(:types)
394
+
395
+ coerce_type = validations[:coerce]
396
+
397
+ # Special case - when the argument is a single type that is a
398
+ # variant-type collection.
399
+ if Types.multiple?(coerce_type) && validations.key?(:type)
400
+ validations[:coerce] = Types::VariantCollectionCoercer.new(
401
+ coerce_type,
402
+ validations.delete(:coerce_with)
403
+ )
404
+ end
405
+ validations.delete(:type)
406
+
407
+ coerce_type
408
+ end
409
+
410
+ # Enforce correct usage of :coerce_with parameter.
411
+ # We do not allow coercion without a type, nor with
412
+ # +JSON+ as a type since this defines its own coercion
413
+ # method.
414
+ def check_coerce_with(validations)
415
+ return unless validations.key?(:coerce_with)
416
+ # type must be supplied for coerce_with..
417
+ raise ArgumentError, 'must supply type for coerce_with' unless validations.key?(:coerce)
418
+
419
+ # but not special JSON types, which
420
+ # already imply coercion method
421
+ return unless SPECIAL_JSON.include?(validations[:coerce])
422
+
423
+ raise ArgumentError, 'coerce_with disallowed for type: JSON'
424
+ end
425
+
426
+ # Add type coercion validation to this scope,
427
+ # if any has been specified.
428
+ # This validation has special handling since it is
429
+ # composited from more than one +requires+/+optional+
430
+ # parameter, and needs to be run before most other
431
+ # validations.
432
+ def coerce_type(validations, attrs, required, opts)
433
+ check_coerce_with(validations)
434
+
435
+ # Falsy check (not key?) is intentional: when a remountable API is first
436
+ # evaluated on its base instance (no configuration supplied yet),
437
+ # configuration[:some_type] evaluates to nil. Skipping instantiation
438
+ # here is correct — the real mounted instance will replay this step with
439
+ # the actual type value.
440
+ return unless validations[:coerce]
441
+
442
+ coerce_options = {
443
+ type: validations[:coerce],
444
+ method: validations[:coerce_with],
445
+ message: validations[:coerce_message]
446
+ }
447
+ validate('coerce', coerce_options, attrs, required, opts)
448
+ end
449
+
450
+ def guess_coerce_type(coerce_type, *values_list)
451
+ return coerce_type unless coerce_type == Array
452
+
453
+ values_list.each do |values|
454
+ next if !values || values.is_a?(Proc)
455
+ return values.first.class if values.is_a?(Range) || !values.empty?
456
+ end
457
+ coerce_type
458
+ end
459
+
460
+ def check_incompatible_option_values(default, values, except_values)
461
+ return unless default && !default.is_a?(Proc)
462
+
463
+ raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :values, values) if values && !values.is_a?(Proc) && !Array(default).all? { |def_val| values.include?(def_val) }
464
+
465
+ return unless except_values && !except_values.is_a?(Proc) && Array(default).any? { |def_val| except_values.include?(def_val) }
466
+
467
+ raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :except, except_values)
468
+ end
469
+
470
+ def validate(type, options, attrs, required, opts)
471
+ validator_class = Validations.require_validator(type)
472
+ validator_instance = validator_class.new(
473
+ attrs,
474
+ options,
475
+ required,
476
+ self,
477
+ opts
478
+ )
479
+ @api.inheritable_setting.namespace_stackable[:validations] = validator_instance
480
+ end
481
+
482
+ def validate_value_coercion(coerce_type, *values_list)
483
+ return unless coerce_type
484
+
485
+ coerce_type = coerce_type.first if coerce_type.is_a?(Enumerable)
486
+ values_list.each do |values|
487
+ next if !values || values.is_a?(Proc)
488
+
489
+ value_types = values.is_a?(Range) ? [values.begin, values.end].compact : values
490
+ value_types = value_types.map { |type| Grape::API::Boolean.build(type) } if coerce_type == Grape::API::Boolean
491
+ raise Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values) unless value_types.all?(coerce_type)
492
+ end
493
+ end
494
+
495
+ def extract_message_option(attrs)
496
+ return nil unless attrs.is_a?(Array)
497
+
498
+ opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
499
+ opts.key?(:message) && !opts[:message].nil? ? opts.delete(:message) : nil
500
+ end
501
+
502
+ def options_key?(type, key, validations)
503
+ validations[type].respond_to?(:key?) && validations[type].key?(key) && !validations[type][key].nil?
504
+ end
505
+
506
+ def all_element_blank?(scoped_params)
507
+ scoped_params.respond_to?(:all?) && scoped_params.all?(&:blank?)
508
+ end
509
+
510
+ # Validators don't have access to each other and they don't need, however,
511
+ # some validators might influence others, so their options should be shared
512
+ def derive_validator_options(validations)
513
+ allow_blank = validations[:allow_blank]
514
+
515
+ {
516
+ allow_blank: allow_blank.is_a?(Hash) ? allow_blank[:value] : allow_blank,
517
+ fail_fast: validations.delete(:fail_fast) || false
518
+ }
519
+ end
520
+
521
+ def validates_presence(validations, attrs, opts)
522
+ return unless validations.key?(:presence) && validations[:presence]
523
+
524
+ validate('presence', validations.delete(:presence), attrs, true, opts)
525
+ validations.delete(:message) if validations.key?(:message)
526
+ end
527
+ end
528
+ end
529
+ end
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module Validations
5
+ class SingleAttributeIterator < AttributesIterator
6
+ private
7
+
8
+ def yield_attributes(val)
9
+ return if skip?(val)
10
+
11
+ @attrs.each do |attr_name|
12
+ yield val, attr_name, empty?(val)
13
+ end
14
+ end
15
+
16
+ # Primitives like Integers and Booleans don't respond to +empty?+.
17
+ # It could be possible to use +blank?+ instead, but
18
+ #
19
+ # false.blank?
20
+ # => true
21
+ def empty?(val)
22
+ val.respond_to?(:empty?) ? val.empty? : val.nil?
23
+ end
24
+ end
25
+ end
26
+ end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module Validations
5
+ module Types
6
+ # Coerces elements in an array. It might be an array of strings or integers or
7
+ # an array of arrays of integers.
8
+ #
9
+ # It could've been possible to use an +of+
10
+ # method (https://dry-rb.org/gems/dry-types/main/array-with-member/)
11
+ # provided by dry-types. Unfortunately, it doesn't work for Grape because of
12
+ # behavior of Virtus which was used earlier, a `Grape::Validations::Types::PrimitiveCoercer`
13
+ # maintains Virtus behavior in coercing.
14
+ class ArrayCoercer < DryTypeCoercer
15
+ def initialize(type, strict = false)
16
+ super
17
+ @coercer = strict ? DryTypes::Strict::Array : DryTypes::Params::Array
18
+ @subtype = type.first
19
+ end
20
+
21
+ def call(_val)
22
+ collection = super
23
+ return collection if collection.is_a?(InvalidValue)
24
+
25
+ coerce_elements collection
26
+ end
27
+
28
+ protected
29
+
30
+ attr_reader :subtype
31
+
32
+ def coerce_elements(collection)
33
+ return if collection.nil?
34
+
35
+ collection.each_with_index do |elem, index|
36
+ return InvalidValue.new if reject?(elem)
37
+
38
+ coerced_elem = elem_coercer.call(elem)
39
+
40
+ return coerced_elem if coerced_elem.is_a?(InvalidValue)
41
+
42
+ collection[index] = coerced_elem
43
+ end
44
+
45
+ collection
46
+ end
47
+
48
+ # This method maintains logic which was defined by Virtus for arrays.
49
+ # Virtus doesn't allow nil in arrays.
50
+ def reject?(val)
51
+ val.nil?
52
+ end
53
+
54
+ def elem_coercer
55
+ @elem_coercer ||= DryTypeCoercer.coercer_instance_for(subtype, strict)
56
+ end
57
+ end
58
+ end
59
+ end
60
+ end