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,293 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module DSL
5
+ module InsideRoute
6
+ include Declared
7
+
8
+ # Backward compatibility: alias exception class to previous location
9
+ MethodNotYetAvailable = Declared::MethodNotYetAvailable
10
+
11
+ # The API version as specified in the URL.
12
+ def version
13
+ env[Grape::Env::API_VERSION]
14
+ end
15
+
16
+ def configuration
17
+ options[:for].configuration.evaluate
18
+ end
19
+
20
+ # End the request and display an error to the
21
+ # end user with the specified message.
22
+ #
23
+ # @param message [String] The message to display.
24
+ # @param status [Integer] The HTTP Status Code. Defaults to default_error_status, 500 if not set.
25
+ # @param additional_headers [Hash] Addtional headers for the response.
26
+ # @param backtrace [Array<String>] The backtrace of the exception that caused the error.
27
+ # @param original_exception [Exception] The original exception that caused the error.
28
+ def error!(message, status = nil, additional_headers = nil, backtrace = nil, original_exception = nil)
29
+ status = self.status(status || inheritable_setting.namespace_inheritable[:default_error_status])
30
+ headers = additional_headers.present? ? header.merge(additional_headers) : header
31
+ throw :error,
32
+ message:,
33
+ status:,
34
+ headers:,
35
+ backtrace:,
36
+ original_exception:
37
+ end
38
+
39
+ # Redirect to a new url.
40
+ #
41
+ # @param url [String] The url to be redirect.
42
+ # @param permanent [Boolean] default false.
43
+ # @param body default a short message including the URL.
44
+ def redirect(url, permanent: false, body: nil)
45
+ body_message = body
46
+ if permanent
47
+ status 301
48
+ body_message ||= "This resource has been moved permanently to #{url}."
49
+ elsif http_version == 'HTTP/1.1' && !request.get?
50
+ status 303
51
+ body_message ||= "An alternate resource is located at #{url}."
52
+ else
53
+ status 302
54
+ body_message ||= "This resource has been moved temporarily to #{url}."
55
+ end
56
+ header 'Location', url
57
+ content_type 'text/plain'
58
+ body body_message
59
+ end
60
+
61
+ # Set or retrieve the HTTP status code.
62
+ #
63
+ # @param status [Integer] The HTTP Status Code to return for this request.
64
+ def status(status = nil)
65
+ case status
66
+ when Symbol
67
+ raise ArgumentError, "Status code :#{status} is invalid." unless Rack::Utils::SYMBOL_TO_STATUS_CODE.key?(status)
68
+
69
+ @status = Rack::Utils.status_code(status)
70
+ when Integer
71
+ @status = status
72
+ when nil
73
+ return @status if @status
74
+
75
+ if request.post?
76
+ 201
77
+ elsif request.delete?
78
+ if @body.present?
79
+ 200
80
+ else
81
+ 204
82
+ end
83
+ else
84
+ 200
85
+ end
86
+ else
87
+ raise ArgumentError, 'Status code must be Integer or Symbol.'
88
+ end
89
+ end
90
+
91
+ # Set response content-type
92
+ def content_type(val = nil)
93
+ if val
94
+ header(Rack::CONTENT_TYPE, val)
95
+ else
96
+ header[Rack::CONTENT_TYPE]
97
+ end
98
+ end
99
+
100
+ # Allows you to define the response body as something other than the
101
+ # return value.
102
+ #
103
+ # @example
104
+ # get '/body' do
105
+ # body "Body"
106
+ # "Not the Body"
107
+ # end
108
+ #
109
+ # GET /body # => "Body"
110
+ def body(value = nil)
111
+ if value
112
+ @body = value
113
+ elsif value == false
114
+ @body = ''
115
+ status 204
116
+ else
117
+ @body
118
+ end
119
+ end
120
+
121
+ # Allows you to explicitly return no content.
122
+ #
123
+ # @example
124
+ # delete :id do
125
+ # return_no_content
126
+ # "not returned"
127
+ # end
128
+ #
129
+ # DELETE /12 # => 204 No Content, ""
130
+ def return_no_content
131
+ status 204
132
+ body false
133
+ end
134
+
135
+ # Allows you to send a file to the client via sendfile.
136
+ #
137
+ # @example
138
+ # get '/file' do
139
+ # sendfile FileStreamer.new(...)
140
+ # end
141
+ #
142
+ # GET /file # => "contents of file"
143
+ def sendfile(value = nil)
144
+ if value.is_a?(String)
145
+ file_body = Grape::ServeStream::FileBody.new(value)
146
+ @stream = Grape::ServeStream::StreamResponse.new(file_body)
147
+ elsif !value.is_a?(NilClass)
148
+ raise ArgumentError, 'Argument must be a file path'
149
+ else
150
+ stream
151
+ end
152
+ end
153
+
154
+ # Allows you to define the response as a streamable object.
155
+ #
156
+ # If Content-Length and Transfer-Encoding are blank (among other conditions),
157
+ # Rack assumes this response can be streamed in chunks.
158
+ #
159
+ # @example
160
+ # get '/stream' do
161
+ # stream FileStreamer.new(...)
162
+ # end
163
+ #
164
+ # GET /stream # => "chunked contents of file"
165
+ #
166
+ # See:
167
+ # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/chunked.rb
168
+ # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/etag.rb
169
+ def stream(value = nil)
170
+ return if value.nil? && @stream.nil?
171
+
172
+ header Rack::CONTENT_LENGTH, nil
173
+ header 'Transfer-Encoding', nil
174
+ header Rack::CACHE_CONTROL, 'no-cache' # Skips ETag generation (reading the response up front)
175
+ if value.is_a?(String)
176
+ file_body = Grape::ServeStream::FileBody.new(value)
177
+ @stream = Grape::ServeStream::StreamResponse.new(file_body)
178
+ elsif value.respond_to?(:each)
179
+ @stream = Grape::ServeStream::StreamResponse.new(value)
180
+ elsif !value.is_a?(NilClass)
181
+ raise ArgumentError, 'Stream object must respond to :each.'
182
+ else
183
+ @stream
184
+ end
185
+ end
186
+
187
+ # Allows you to make use of Grape Entities by setting
188
+ # the response body to the serializable hash of the
189
+ # entity provided in the `:with` option. This has the
190
+ # added benefit of automatically passing along environment
191
+ # and version information to the serialization, making it
192
+ # very easy to do conditional exposures. See Entity docs
193
+ # for more info.
194
+ #
195
+ # @example
196
+ #
197
+ # get '/users/:id' do
198
+ # present User.find(params[:id]),
199
+ # with: API::Entities::User,
200
+ # admin: current_user.admin?
201
+ # end
202
+ def present(*args, **options)
203
+ key, object = if args.count == 2 && args.first.is_a?(Symbol)
204
+ args
205
+ else
206
+ [nil, args.first]
207
+ end
208
+ entity_class = entity_class_for_obj(object, options)
209
+
210
+ root = options.delete(:root)
211
+
212
+ representation = if entity_class
213
+ entity_representation_for(entity_class, object, options)
214
+ else
215
+ object
216
+ end
217
+
218
+ representation = { root => representation } if root
219
+
220
+ if key
221
+ representation = (body || {}).merge(key => representation)
222
+ elsif entity_class.present? && body
223
+ raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
224
+
225
+ representation = body.merge(representation)
226
+ end
227
+
228
+ body representation
229
+ end
230
+
231
+ # Returns route information for the current request.
232
+ #
233
+ # @example
234
+ #
235
+ # desc "Returns the route description."
236
+ # get '/' do
237
+ # route.description
238
+ # end
239
+ def route
240
+ env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info]
241
+ end
242
+
243
+ # Attempt to locate the Entity class for a given object, if not given
244
+ # explicitly. This is done by looking for the presence of Klass::Entity,
245
+ # where Klass is the class of the `object` parameter, or one of its
246
+ # ancestors.
247
+ # @param object [Object] the object to locate the Entity class for
248
+ # @param options [Hash]
249
+ # @option options :with [Class] the explicit entity class to use
250
+ # @return [Class] the located Entity class, or nil if none is found
251
+ def entity_class_for_obj(object, options)
252
+ entity_class = options.delete(:with)
253
+ return entity_class if entity_class
254
+
255
+ # entity class not explicitly defined, auto-detect from relation#klass or first object in the collection
256
+ object_class = if object.respond_to?(:klass)
257
+ object.klass
258
+ else
259
+ object.respond_to?(:first) ? object.first.class : object.class
260
+ end
261
+
262
+ representations = inheritable_setting.namespace_stackable_with_hash(:representations)
263
+ if representations
264
+ potential = object_class.ancestors.detect { |potential| representations.key?(potential) }
265
+ entity_class = representations[potential] if potential
266
+ end
267
+
268
+ entity_class = object_class.const_get(:Entity) if !entity_class && object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
269
+ entity_class
270
+ end
271
+
272
+ # @return the representation of the given object as done through
273
+ # the given entity_class.
274
+ def entity_representation_for(entity_class, object, options)
275
+ embeds = { env: }
276
+ embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
277
+ entity_class.represent(object, **embeds, **options)
278
+ end
279
+
280
+ def http_version
281
+ env.fetch('HTTP_VERSION') { env[Rack::SERVER_PROTOCOL] }
282
+ end
283
+
284
+ def api_format(format)
285
+ env[Grape::Env::API_FORMAT] = format
286
+ end
287
+
288
+ def context
289
+ self
290
+ end
291
+ end
292
+ end
293
+ end
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module DSL
5
+ module Logger
6
+ # Set or retrive the configured logger. If none was configured, this
7
+ # method will create a new one, logging to stdout.
8
+ # @param logger [Object] the new logger to use
9
+ def logger(logger = nil)
10
+ global_settings = inheritable_setting.global
11
+ if logger
12
+ global_settings[:logger] = logger
13
+ else
14
+ global_settings[:logger] || global_settings[:logger] = ::Logger.new($stdout)
15
+ end
16
+ end
17
+ end
18
+ end
19
+ end
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module DSL
5
+ module Middleware
6
+ # Apply a custom middleware to the API. Applies
7
+ # to the current namespace and any children, but
8
+ # not parents.
9
+ #
10
+ # @param middleware_class [Class] The class of the middleware you'd like
11
+ # to inject.
12
+ def use(middleware_class, *args, &block)
13
+ arr = [:use, middleware_class, *args]
14
+ arr << block if block
15
+
16
+ inheritable_setting.namespace_stackable[:middleware] = arr
17
+ end
18
+
19
+ %i[insert insert_before insert_after].each do |method_name|
20
+ define_method method_name do |*args, &block|
21
+ arr = [method_name, *args]
22
+ arr << block if block
23
+
24
+ inheritable_setting.namespace_stackable[:middleware] = arr
25
+ end
26
+ end
27
+
28
+ # Retrieve an array of the middleware classes
29
+ # and arguments that are currently applied to the
30
+ # application.
31
+ def middleware
32
+ inheritable_setting.namespace_stackable[:middleware] || []
33
+ end
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,239 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module DSL
5
+ # Defines DSL methods, meant to be applied to a ParamsScope, which define
6
+ # and describe the parameters accepted by an endpoint, or all endpoints
7
+ # within a namespace.
8
+ module Parameters
9
+ # Set the module used to build the request.params.
10
+ #
11
+ # @param build_with the ParamBuilder module to use when building request.params
12
+ # Available builders are:
13
+ #
14
+ # * Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder (default)
15
+ # * Grape::Extensions::Hash::ParamBuilder
16
+ # * Grape::Extensions::Hashie::Mash::ParamBuilder
17
+ #
18
+ # @example
19
+ #
20
+ # require 'grape/extenstions/hashie_mash'
21
+ # class API < Grape::API
22
+ # desc "Get collection"
23
+ # params do
24
+ # build_with :hashie_mash
25
+ # requires :user_id, type: Integer
26
+ # end
27
+ # get do
28
+ # params['user_id']
29
+ # end
30
+ # end
31
+ def build_with(build_with)
32
+ @api.inheritable_setting.namespace_inheritable[:build_params_with] = build_with
33
+ end
34
+
35
+ # Include reusable params rules among current.
36
+ # You can define reusable params with helpers method.
37
+ #
38
+ # @example
39
+ #
40
+ # class API < Grape::API
41
+ # helpers do
42
+ # params :pagination do
43
+ # optional :page, type: Integer
44
+ # optional :per_page, type: Integer
45
+ # end
46
+ # end
47
+ #
48
+ # desc "Get collection"
49
+ # params do
50
+ # use :pagination
51
+ # end
52
+ # get do
53
+ # Collection.page(params[:page]).per(params[:per_page])
54
+ # end
55
+ # end
56
+ def use(*names, **options)
57
+ named_params = @api.inheritable_setting.namespace_stackable_with_hash(:named_params) || {}
58
+ names.each do |name|
59
+ params_block = named_params.fetch(name) do
60
+ raise "Params :#{name} not found!"
61
+ end
62
+
63
+ if options.empty?
64
+ instance_exec(options, &params_block)
65
+ else
66
+ instance_exec(**options, &params_block)
67
+ end
68
+ end
69
+ end
70
+ alias use_scope use
71
+ alias includes use
72
+
73
+ # Require one or more parameters for the current endpoint.
74
+ #
75
+ # @param attrs list of parameters names, or, if :using is
76
+ # passed as an option, which keys to include (:all or :none) from
77
+ # the :using hash. The last key can be a hash, which specifies
78
+ # options for the parameters
79
+ # @option attrs :type [Class] the type to coerce this parameter to before
80
+ # passing it to the endpoint. See {Grape::Validations::Types} for a list of
81
+ # types that are supported automatically. Custom classes may be used
82
+ # where they define a class-level `::parse` method, or in conjunction
83
+ # with the `:coerce_with` parameter. `JSON` may be supplied to denote
84
+ # `JSON`-formatted objects or arrays of objects. `Array[JSON]` accepts
85
+ # the same values as `JSON` but will wrap single objects in an `Array`.
86
+ # @option attrs :types [Array<Class>] may be supplied in place of +:type+
87
+ # to declare an attribute that has multiple allowed types. See
88
+ # {Validations::Types::MultipleTypeCoercer} for more details on coercion
89
+ # and validation rules for variant-type parameters.
90
+ # @option attrs :desc [String] description to document this parameter
91
+ # @option attrs :default [Object] default value, if parameter is optional
92
+ # @option attrs :values [Array] permissable values for this field. If any
93
+ # other value is given, it will be handled as a validation error
94
+ # @option attrs :using [Hash[Symbol => Hash]] a hash defining keys and
95
+ # options, like that returned by {Grape::Entity#documentation}. The value
96
+ # of each key is an options hash accepting the same parameters
97
+ # @option attrs :except [Array[Symbol]] a list of keys to exclude from
98
+ # the :using Hash. The meaning of this depends on if :all or :none was
99
+ # passed; :all + :except will make the :except fields optional, whereas
100
+ # :none + :except will make the :except fields required
101
+ # @option attrs :coerce_with [#parse, #call] method to be used when coercing
102
+ # the parameter to the type named by `attrs[:type]`. Any class or object
103
+ # that defines `::parse` or `::call` may be used.
104
+ #
105
+ # @example
106
+ #
107
+ # params do
108
+ # # Basic usage: require a parameter of a certain type
109
+ # requires :user_id, type: Integer
110
+ #
111
+ # # You don't need to specify type; String is default
112
+ # requires :foo
113
+ #
114
+ # # Multiple params can be specified at once if they share
115
+ # # the same options.
116
+ # requires :x, :y, :z, type: Date
117
+ #
118
+ # # Nested parameters can be handled as hashes. You must
119
+ # # pass in a block, within which you can use any of the
120
+ # # parameters DSL methods.
121
+ # requires :user, type: Hash do
122
+ # requires :name, type: String
123
+ # end
124
+ # end
125
+ def requires(*attrs, **opts, &block)
126
+ opts[:presence] = { value: true, message: opts[:message] }
127
+ opts = @group.deep_merge(opts) if @group
128
+
129
+ if opts[:using]
130
+ require_required_and_optional_fields(attrs.first, using: opts[:using], except: opts[:except])
131
+ else
132
+ validate_attributes(attrs, **opts, &block)
133
+ block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], &block) : push_declared_params(attrs, as: opts[:as])
134
+ end
135
+ end
136
+
137
+ # Allow, but don't require, one or more parameters for the current
138
+ # endpoint.
139
+ # @param (see #requires)
140
+ # @option (see #requires)
141
+ def optional(*attrs, **opts, &block)
142
+ type = opts[:type]
143
+ opts = @group.deep_merge(opts) if @group
144
+
145
+ # check type for optional parameter group
146
+ if attrs && block
147
+ raise Grape::Exceptions::MissingGroupType if type.nil?
148
+ raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
149
+ end
150
+
151
+ if opts[:using]
152
+ require_optional_fields(attrs.first, using: opts[:using], except: opts[:except])
153
+ else
154
+ validate_attributes(attrs, **opts, &block)
155
+
156
+ block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], optional: true, &block) : push_declared_params(attrs, as: opts[:as])
157
+ end
158
+ end
159
+
160
+ # Define common settings for one or more parameters
161
+ # @param (see #requires)
162
+ # @option (see #requires)
163
+ def with(**opts, &)
164
+ new_group_attrs = @group&.deep_merge(opts) || opts
165
+ new_group_scope(new_group_attrs, &)
166
+ end
167
+
168
+ %i[mutually_exclusive exactly_one_of at_least_one_of all_or_none_of].each do |validator|
169
+ define_method validator do |*attrs, message: nil|
170
+ validates(attrs, validator => { value: true, message: })
171
+ end
172
+ end
173
+
174
+ # Define a block of validations which should be applied if and only if
175
+ # the given parameter is present. The parameters are not nested.
176
+ # @param attr [Symbol] the parameter which, if present, triggers the
177
+ # validations
178
+ # @raise Grape::Exceptions::UnknownParameter if `attr` has not been
179
+ # defined in this scope yet
180
+ # @yield a parameter definition DSL
181
+ def given(*attrs, &)
182
+ attrs.each do |attr|
183
+ proxy_attr = first_hash_key_or_param(attr)
184
+ raise Grape::Exceptions::UnknownParameter.new(proxy_attr) unless declared_param?(proxy_attr)
185
+ end
186
+ new_lateral_scope(dependent_on: attrs, &)
187
+ end
188
+
189
+ # Test for whether a certain parameter has been defined in this params
190
+ # block yet.
191
+ # @return [Boolean] whether the parameter has been defined
192
+ def declared_param?(param)
193
+ if lateral?
194
+ # Elements of @declared_params of lateral scope are pushed in @parent. So check them in @parent.
195
+ @parent.declared_param?(param)
196
+ else
197
+ # @declared_params also includes hashes of options and such, but those
198
+ # won't be flattened out.
199
+ @declared_params.flatten.any? do |declared_param_attr|
200
+ first_hash_key_or_param(declared_param_attr.key) == param
201
+ end
202
+ end
203
+ end
204
+
205
+ alias group requires
206
+
207
+ class EmptyOptionalValue; end # rubocop:disable Lint/EmptyClass
208
+
209
+ def map_params(params, element, is_array = false)
210
+ if params.is_a?(Array)
211
+ params.map do |el|
212
+ map_params(el, element, true)
213
+ end
214
+ elsif params.is_a?(Hash)
215
+ params[element] || (@optional && is_array ? EmptyOptionalValue : {})
216
+ elsif params == EmptyOptionalValue
217
+ EmptyOptionalValue
218
+ else
219
+ {}
220
+ end
221
+ end
222
+
223
+ # @param params [Hash] initial hash of parameters
224
+ # @return hash of parameters relevant for the current scope
225
+ # @api private
226
+ def params(params)
227
+ params = @parent.qualifying_params.presence || @parent.params(params) if @parent
228
+ params = map_params(params, @element) if @element
229
+ params
230
+ end
231
+
232
+ private
233
+
234
+ def first_hash_key_or_param(parameter)
235
+ parameter.is_a?(Hash) ? parameter.keys.first : parameter
236
+ end
237
+ end
238
+ end
239
+ end