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
data/lib/grape/api.rb CHANGED
@@ -1,540 +1,165 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Grape
2
- # The API class is the primary entry point for
3
- # creating Grape APIs.Users should subclass this
4
- # class in order to build an API.
4
+ # The API class is the primary entry point for creating Grape APIs. Users
5
+ # should subclass this class in order to build an API.
5
6
  class API
6
- extend Validations::ClassMethods
7
+ # Class methods that we want to call on the API rather than on the API object
8
+ NON_OVERRIDABLE = %i[base= base_instance? call change! configuration compile! inherit_settings recognize_path reset! routes top_level_setting= top_level_setting].freeze
7
9
 
8
- class << self
9
- attr_reader :route_set
10
- attr_reader :versions
11
- attr_reader :routes
12
- attr_reader :settings
13
- attr_writer :logger
14
- attr_reader :endpoints
15
- attr_reader :mountings
16
- attr_reader :instance
10
+ Helpers = Grape::DSL::Helpers::BaseHelper
17
11
 
18
- def logger(logger = nil)
19
- if logger
20
- @logger = logger
21
- else
22
- @logger ||= Logger.new($stdout)
23
- end
24
- end
25
-
26
- def reset!
27
- @settings = Grape::Util::HashStack.new
28
- @route_set = Rack::Mount::RouteSet.new
29
- @endpoints = []
30
- @mountings = []
31
- @routes = nil
32
- reset_validations!
33
- end
34
-
35
- def compile
36
- @instance = self.new
37
- end
38
-
39
- def change!
40
- @instance = nil
41
- end
42
-
43
- def call(env)
44
- compile unless instance
45
- call!(env)
46
- end
12
+ class Boolean
13
+ def self.build(val)
14
+ return nil if val != true && val != false
47
15
 
48
- def call!(env)
49
- instance.call(env)
16
+ new
50
17
  end
18
+ end
51
19
 
52
- # Set a configuration value for this namespace.
53
- #
54
- # @param key [Symbol] The key of the configuration variable.
55
- # @param value [Object] The value to which to set the configuration variable.
56
- def set(key, value)
57
- settings[key.to_sym] = value
58
- end
20
+ class << self
21
+ extend Forwardable
59
22
 
60
- # Add to a configuration value for this
61
- # namespace.
62
- #
63
- # @param key [Symbol] The key of the configuration variable.
64
- # @param value [Object] The value to which to set the configuration variable.
65
- def imbue(key, value)
66
- settings.imbue(key, value)
67
- end
23
+ attr_accessor :base_instance, :instances
68
24
 
69
- # Define a root URL prefix for your entire API.
70
- def prefix(prefix = nil)
71
- prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
72
- end
25
+ delegate_missing_to :base_instance
73
26
 
74
- # Do not route HEAD requests to GET requests automatically
75
- def do_not_route_head!
76
- set(:do_not_route_head, true)
77
- end
27
+ # This is the interface point between Rack and Grape; it accepts a request
28
+ # from Rack and ultimately returns an array of three values: the status,
29
+ # the headers, and the body. See [the rack specification]
30
+ # (https://github.com/rack/rack/blob/main/SPEC.rdoc) for more.
31
+ # NOTE: This will only be called on an API directly mounted on RACK
32
+ def_delegators :base_instance, :new, :configuration, :call, :change!, :compile!, :recognize_path, :routes
78
33
 
79
- # Do not automatically route OPTIONS
80
- def do_not_route_options!
81
- set(:do_not_route_options, true)
34
+ # Initialize the instance variables on the remountable class, and the base_instance
35
+ # an instance that will be used to create the set up but will not be mounted
36
+ def initial_setup(base_instance_parent)
37
+ @instances = []
38
+ @setup = []
39
+ @base_parent = base_instance_parent
40
+ @base_instance = mount_instance
82
41
  end
83
42
 
84
- # Specify an API version.
85
- #
86
- # @example API with legacy support.
87
- # class MyAPI < Grape::API
88
- # version 'v2'
89
- #
90
- # get '/main' do
91
- # {:some => 'data'}
92
- # end
93
- #
94
- # version 'v1' do
95
- # get '/main' do
96
- # {:legacy => 'data'}
97
- # end
98
- # end
99
- # end
100
- #
101
- def version(*args, &block)
102
- if args.any?
103
- options = args.pop if args.last.is_a? Hash
104
- options ||= {}
105
- options = {:using => :path}.merge!(options)
106
-
107
- raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.has_key?(:vendor)
108
-
109
- @versions = versions | args
110
- nest(block) do
111
- set(:version, args)
112
- set(:version_options, options)
43
+ # Redefines all methods so that are forwarded to add_setup and be recorded
44
+ def override_all_methods!
45
+ (base_instance.methods - Class.methods - NON_OVERRIDABLE).each do |method_override|
46
+ define_singleton_method(method_override) do |*args, **kwargs, &block|
47
+ add_setup(method: method_override, args:, kwargs:, block:)
113
48
  end
114
49
  end
115
-
116
- @versions.last unless @versions.nil?
117
50
  end
118
51
 
119
- # Add a description to the next namespace or function.
120
- def desc(description, options = {})
121
- @last_description = options.merge(:description => description)
122
- end
123
-
124
- # Specify the default format for the API's serializers.
125
- # May be `:json` or `:txt` (default).
126
- def default_format(new_format = nil)
127
- new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
128
- end
129
-
130
- # Specify the format for the API's serializers.
131
- # May be `:json`, `:xml`, `:txt`, etc.
132
- def format(new_format = nil)
133
- if new_format
134
- set(:format, new_format.to_sym)
135
- # define the default error formatters
136
- set(:default_error_formatter, Grape::ErrorFormatter::Base.formatter_for(new_format, {}))
137
- # define a single mime type
138
- mime_type = content_types[new_format.to_sym]
139
- raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type
140
- settings.imbue(:content_types, new_format.to_sym => mime_type)
52
+ # Configure an API from the outside. If a block is given, it'll pass a
53
+ # configuration hash to the block which you can use to configure your
54
+ # API. If no block is given, returns the configuration hash.
55
+ # The configuration set here is accessible from inside an API with
56
+ # `configuration` as normal.
57
+ def configure
58
+ config = @base_instance.configuration
59
+ if block_given?
60
+ yield config
61
+ self
141
62
  else
142
- settings[:format]
63
+ config
143
64
  end
144
65
  end
145
66
 
146
- # Specify a custom formatter for a content-type.
147
- def formatter(content_type, new_formatter)
148
- settings.imbue(:formatters, content_type.to_sym => new_formatter)
149
- end
150
-
151
- # Specify a custom parser for a content-type.
152
- def parser(content_type, new_parser)
153
- settings.imbue(:parsers, content_type.to_sym => new_parser)
154
- end
155
-
156
- # Specify a default error formatter.
157
- def default_error_formatter(new_formatter = nil)
158
- new_formatter ? set(:default_error_formatter, new_formatter) : settings[:default_error_formatter]
159
- end
160
-
161
- def error_formatter(format, new_formatter)
162
- settings.imbue(:error_formatters, format.to_sym => new_formatter)
163
- end
164
-
165
- # Specify additional content-types, e.g.:
166
- # content_type :xls, 'application/vnd.ms-excel'
167
- def content_type(key, val)
168
- settings.imbue(:content_types, key.to_sym => val)
169
- end
170
-
171
- # All available content types.
172
- def content_types
173
- Grape::ContentTypes.content_types_for(settings[:content_types])
67
+ # The remountable class can have a configuration hash to provide some dynamic class-level variables.
68
+ # For instance, a description could be done using: `desc configuration[:description]` if it may vary
69
+ # depending on where the endpoint is mounted. Use with care, if you find yourself using configuration
70
+ # too much, you may actually want to provide a new API rather than remount it.
71
+ def mount_instance(configuration: nil)
72
+ Class.new(@base_parent).tap do |instance|
73
+ instance.configuration = Grape::Util::EndpointConfiguration.new(configuration || {})
74
+ instance.base = self
75
+ replay_setup_on(instance)
76
+ end
174
77
  end
175
78
 
176
- # Specify the default status code for errors.
177
- def default_error_status(new_status = nil)
178
- new_status ? set(:default_error_status, new_status) : settings[:default_error_status]
179
- end
79
+ private
180
80
 
181
- # Allows you to rescue certain exceptions that occur to return
182
- # a grape error rather than raising all the way to the
183
- # server level.
184
- #
185
- # @example Rescue from custom exceptions
186
- # class ExampleAPI < Grape::API
187
- # class CustomError < StandardError; end
188
- #
189
- # rescue_from CustomError
190
- # end
191
- #
192
- # @overload rescue_from(*exception_classes, options = {})
193
- # @param [Array] exception_classes A list of classes that you want to rescue, or
194
- # the symbol :all to rescue from all exceptions.
195
- # @param [Block] block Execution block to handle the given exception.
196
- # @param [Hash] options Options for the rescue usage.
197
- # @option options [Boolean] :backtrace Include a backtrace in the rescue response.
198
- def rescue_from(*args, &block)
199
- if block_given?
200
- args.each do |arg|
201
- imbue(:rescue_handlers, { arg => block })
202
- end
203
- end
204
- imbue(:rescue_options, args.pop) if args.last.is_a?(Hash)
205
- set(:rescue_all, true) and return if args.include?(:all)
206
- imbue(:rescued_errors, args)
207
- end
81
+ # When inherited, will create a list of all instances (times the API was mounted)
82
+ # It will listen to the setup required to mount that endpoint, and replicate it on any new instance
83
+ def inherited(api)
84
+ super
208
85
 
209
- # Allows you to specify a default representation entity for a
210
- # class. This allows you to map your models to their respective
211
- # entities once and then simply call `present` with the model.
212
- #
213
- # @example
214
- # class ExampleAPI < Grape::API
215
- # represent User, :with => Entity::User
216
- #
217
- # get '/me' do
218
- # present current_user # :with => Entity::User is assumed
219
- # end
220
- # end
221
- #
222
- # Note that Grape will automatically go up the class ancestry to
223
- # try to find a representing entity, so if you, for example, define
224
- # an entity to represent `Object` then all presented objects will
225
- # bubble up and utilize the entity provided on that `represent` call.
226
- #
227
- # @param model_class [Class] The model class that will be represented.
228
- # @option options [Class] :with The entity class that will represent the model.
229
- def represent(model_class, options)
230
- raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with] && options[:with].is_a?(Class)
231
- imbue(:representations, model_class => options[:with])
86
+ api.initial_setup(self == Grape::API ? Grape::API::Instance : @base_instance)
87
+ api.override_all_methods!
232
88
  end
233
89
 
234
- # Add helper methods that will be accessible from any
235
- # endpoint within this namespace (and child namespaces).
236
- #
237
- # When called without a block, all known helpers within this scope
238
- # are included.
239
- #
240
- # @param [Module] new_mod optional module of methods to include
241
- # @param [Block] block optional block of methods to include
242
- #
243
- # @example Define some helpers.
244
- #
245
- # class ExampleAPI < Grape::API
246
- # helpers do
247
- # def current_user
248
- # User.find_by_id(params[:token])
249
- # end
250
- # end
251
- # end
252
- #
253
- def helpers(new_mod = nil, &block)
254
- if block_given? || new_mod
255
- mod = settings.peek[:helpers] || Module.new
256
- if new_mod
257
- mod.class_eval do
258
- include new_mod
259
- end
260
- end
261
- mod.class_eval &block if block_given?
262
- set(:helpers, mod)
263
- else
264
- mod = Module.new
265
- settings.stack.each do |s|
266
- mod.send :include, s[:helpers] if s[:helpers]
267
- end
268
- change!
269
- mod
90
+ # Replays the set up to produce an API as defined in this class, can be called
91
+ # on classes that inherit from Grape::API
92
+ def replay_setup_on(instance)
93
+ @setup.each do |setup_step|
94
+ replay_step_on(instance, **setup_step)
270
95
  end
271
96
  end
272
97
 
273
- # Add an authentication type to the API. Currently
274
- # only `:http_basic`, `:http_digest` and `:oauth2` are supported.
275
- def auth(type = nil, options = {}, &block)
276
- if type
277
- set(:auth, {:type => type.to_sym, :proc => block}.merge(options))
278
- else
279
- settings[:auth]
98
+ # Adds a new stage to the set up require to get a Grape::API up and running
99
+ def add_setup(**step)
100
+ @setup << step
101
+ last_response = nil
102
+ @instances.each do |instance|
103
+ last_response = replay_step_on(instance, **step)
280
104
  end
281
- end
282
105
 
283
- # Add HTTP Basic authorization to the API.
284
- #
285
- # @param [Hash] options A hash of options.
286
- # @option options [String] :realm "API Authorization" The HTTP Basic realm.
287
- def http_basic(options = {}, &block)
288
- options[:realm] ||= "API Authorization"
289
- auth :http_basic, options, &block
106
+ refresh_mount_step if step[:method] != :mount
107
+ last_response
290
108
  end
291
109
 
292
- def http_digest(options = {}, &block)
293
- options[:realm] ||= "API Authorization"
294
- options[:opaque] ||= "secret"
295
- auth :http_digest, options, &block
296
- end
110
+ # Updating all previously mounted classes in the case that new methods have been executed.
111
+ def refresh_mount_step
112
+ @setup.each do |setup_step|
113
+ next if setup_step[:method] != :mount
297
114
 
298
- def mount(mounts)
299
- mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
300
- mounts.each_pair do |app, path|
301
- if app.respond_to?(:inherit_settings, true)
302
- app_settings = settings.clone
303
- mount_path = Rack::Mount::Utils.normalize_path([ settings[:mount_path], path ].compact.join("/"))
304
- app_settings.set :mount_path, mount_path
305
- app.inherit_settings(app_settings)
115
+ refresh_mount_step = setup_step.merge(method: :refresh_mounted_api)
116
+ @setup << refresh_mount_step
117
+ @instances.each do |instance|
118
+ replay_step_on(instance, **refresh_mount_step)
306
119
  end
307
- endpoints << Grape::Endpoint.new(settings.clone, {
308
- :method => :any,
309
- :path => path,
310
- :app => app
311
- })
312
120
  end
313
121
  end
314
122
 
315
- # Defines a route that will be recognized
316
- # by the Grape API.
317
- #
318
- # @param methods [HTTP Verb] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
319
- # @param paths [String] One or more strings representing the URL segment(s) for this route.
320
- #
321
- # @example Defining a basic route.
322
- # class MyAPI < Grape::API
323
- # route(:any, '/hello') do
324
- # {:hello => 'world'}
325
- # end
326
- # end
327
- def route(methods, paths = ['/'], route_options = {}, &block)
328
- endpoint_options = {
329
- :method => methods,
330
- :path => paths,
331
- :route_options => (@namespace_description || {}).deep_merge(@last_description || {}).deep_merge(route_options || {})
332
- }
333
- endpoints << Grape::Endpoint.new(settings.clone, endpoint_options, &block)
123
+ def replay_step_on(instance, method:, args:, kwargs:, block:)
124
+ return if skip_immediate_run?(instance, args, kwargs)
334
125
 
335
- @last_description = nil
336
- reset_validations!
337
- end
338
-
339
- def before(&block)
340
- imbue(:befores, [block])
341
- end
342
-
343
- def after_validation(&block)
344
- imbue(:after_validations, [block])
345
- end
346
-
347
- def after(&block)
348
- imbue(:afters, [block])
349
- end
350
-
351
- def get(paths = ['/'], options = {}, &block); route('GET', paths, options, &block) end
352
- def post(paths = ['/'], options = {}, &block); route('POST', paths, options, &block) end
353
- def put(paths = ['/'], options = {}, &block); route('PUT', paths, options, &block) end
354
- def head(paths = ['/'], options = {}, &block); route('HEAD', paths, options, &block) end
355
- def delete(paths = ['/'], options = {}, &block); route('DELETE', paths, options, &block) end
356
- def options(paths = ['/'], options = {}, &block); route('OPTIONS', paths, options, &block) end
357
- def patch(paths = ['/'], options = {}, &block); route('PATCH', paths, options, &block) end
358
-
359
- def namespace(space = nil, options = {}, &block)
360
- if space || block_given?
361
- previous_namespace_description = @namespace_description
362
- @namespace_description = (@namespace_description || {}).deep_merge(@last_description || {})
363
- @last_description = nil
364
- nest(block) do
365
- set(:namespace, Namespace.new(space, options)) if space
366
- end
367
- @namespace_description = previous_namespace_description
126
+ eval_args = evaluate_arguments(instance.configuration, *args)
127
+ eval_kwargs = kwargs.deep_transform_values { |v| evaluate_arguments(instance.configuration, v).first }
128
+ response = instance.__send__(method, *eval_args, **eval_kwargs, &block)
129
+ if skip_immediate_run?(instance, [response], kwargs)
130
+ response
368
131
  else
369
- Namespace.joined_space_path(settings)
370
- end
371
- end
372
-
373
- # Thie method allows you to quickly define a parameter route segment
374
- # in your API.
375
- #
376
- # @param param [Symbol] The name of the parameter you wish to declare.
377
- # @option options [Regexp] You may supply a regular expression that the declared parameter must meet.
378
- def route_param(param, options = {}, &block)
379
- options = options.dup
380
- options[:requirements] = { param.to_sym => options[:requirements] } if options[:requirements].is_a?(Regexp)
381
- namespace(":#{param}", options, &block)
382
- end
383
-
384
- alias_method :group, :namespace
385
- alias_method :resource, :namespace
386
- alias_method :resources, :namespace
387
- alias_method :segment, :namespace
388
-
389
- # Create a scope without affecting the URL.
390
- #
391
- # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
392
- def scope(name = nil, &block)
393
- nest(block)
394
- end
395
-
396
- # Apply a custom middleware to the API. Applies
397
- # to the current namespace and any children, but
398
- # not parents.
399
- #
400
- # @param middleware_class [Class] The class of the middleware you'd like
401
- # to inject.
402
- def use(middleware_class, *args, &block)
403
- arr = [middleware_class, *args]
404
- arr << block if block_given?
405
- imbue(:middleware, [arr])
406
- end
407
-
408
- # Retrieve an array of the middleware classes
409
- # and arguments that are currently applied to the
410
- # application.
411
- def middleware
412
- settings.stack.inject([]){|a,s| a += s[:middleware] if s[:middleware]; a}
413
- end
414
-
415
- # An array of API routes.
416
- def routes
417
- @routes ||= prepare_routes
418
- end
419
-
420
- def versions
421
- @versions ||= []
422
- end
423
-
424
- def cascade(value = nil)
425
- value.nil? ?
426
- (settings.has_key?(:cascade) ? !! settings[:cascade] : true) :
427
- set(:cascade, value)
428
- end
429
-
430
- protected
431
-
432
- def prepare_routes
433
- routes = []
434
- endpoints.each do |endpoint|
435
- routes.concat(endpoint.routes)
132
+ evaluate_arguments(instance.configuration, response).first
436
133
  end
437
- routes
438
134
  end
439
135
 
440
- # Execute first the provided block, then each of the
441
- # block passed in. Allows for simple 'before' setups
442
- # of settings stack pushes.
443
- def nest(*blocks, &block)
444
- blocks.reject!{|b| b.nil?}
445
- if blocks.any?
446
- settings.push # create a new context to eval the follow
447
- instance_eval &block if block_given?
448
- blocks.each{|b| instance_eval &b}
449
- settings.pop # when finished, we pop the context
450
- reset_validations!
451
- else
452
- instance_eval &block
453
- end
136
+ # Skips steps that contain arguments to be lazily executed (on re-mount time)
137
+ def skip_immediate_run?(instance, args, kwargs)
138
+ instance.base_instance? &&
139
+ (any_lazy?(args) || args.any? { |arg| arg.is_a?(Hash) && any_lazy?(arg.values) } || any_lazy?(kwargs.values))
454
140
  end
455
141
 
456
- def inherited(subclass)
457
- subclass.reset!
458
- subclass.logger = logger.clone
142
+ def any_lazy?(args)
143
+ args.any? { |argument| argument_lazy?(argument) }
459
144
  end
460
145
 
461
- def inherit_settings(other_stack)
462
- settings.prepend other_stack
463
- endpoints.each do |e|
464
- e.settings.prepend(other_stack)
465
- e.options[:app].inherit_settings(other_stack) if e.options[:app].respond_to?(:inherit_settings, true)
146
+ def evaluate_arguments(configuration, *args)
147
+ args.map do |argument|
148
+ if argument_lazy?(argument)
149
+ argument.evaluate_from(configuration)
150
+ elsif argument.is_a?(Hash)
151
+ argument.transform_values { |value| evaluate_arguments(configuration, value).first }
152
+ elsif argument.is_a?(Array)
153
+ evaluate_arguments(configuration, *argument)
154
+ else
155
+ argument
156
+ end
466
157
  end
467
158
  end
468
- end
469
-
470
- def initialize
471
- @route_set = Rack::Mount::RouteSet.new
472
- self.class.endpoints.each do |endpoint|
473
- endpoint.mount_in(@route_set)
474
- end
475
- add_head_not_allowed_methods
476
- @route_set.freeze
477
- end
478
159
 
479
- def call(env)
480
- status, headers, body = @route_set.call(env)
481
- headers.delete('X-Cascade') unless cascade?
482
- [ status, headers, body ]
483
- end
484
-
485
- # Some requests may return a HTTP 404 error if grape cannot find a matching
486
- # route. In this case, Rack::Mount adds a X-Cascade header to the response
487
- # and sets it to 'pass', indicating to grape's parents they should keep
488
- # looking for a matching route on other resources.
489
- #
490
- # In some applications (e.g. mounting grape on rails), one might need to trap
491
- # errors from reaching upstream. This is effectivelly done by unsetting
492
- # X-Cascade. Default :cascade is true.
493
- def cascade?
494
- return !! self.class.settings[:cascade] if self.class.settings.has_key?(:cascade)
495
- return !! self.class.settings[:version_options][:cascade] if self.class.settings[:version_options] && self.class.settings[:version_options].has_key?(:cascade)
496
- true
497
- end
498
-
499
- reset!
500
-
501
- private
502
-
503
- # For every resource add a 'OPTIONS' route that returns an HTTP 204 response
504
- # with a list of HTTP methods that can be called. Also add a route that
505
- # will return an HTTP 405 response for any HTTP method that the resource
506
- # cannot handle.
507
- def add_head_not_allowed_methods
508
- allowed_methods = Hash.new{|h,k| h[k] = [] }
509
- resources = self.class.endpoints.map do |endpoint|
510
- endpoint.options[:app] && endpoint.options[:app].respond_to?(:endpoints) ?
511
- endpoint.options[:app].endpoints.map(&:routes) :
512
- endpoint.routes
513
- end
514
- resources.flatten.each do |route|
515
- allowed_methods[route.route_compiled] << route.route_method
516
- end
517
- allowed_methods.each do |path_info, methods|
518
- if methods.include?('GET') && ! methods.include?("HEAD") && ! self.class.settings[:do_not_route_head]
519
- methods = methods | [ 'HEAD' ]
520
- end
521
- allow_header = (["OPTIONS"] | methods).join(", ")
522
- unless methods.include?("OPTIONS") || self.class.settings[:do_not_route_options]
523
- @route_set.add_route( proc { [204, { 'Allow' => allow_header }, []]}, {
524
- :path_info => path_info,
525
- :request_method => "OPTIONS"
526
- })
527
- end
528
- not_allowed_methods = %w(GET PUT POST DELETE PATCH HEAD) - methods
529
- not_allowed_methods << "OPTIONS" if self.class.settings[:do_not_route_options]
530
- not_allowed_methods.each do |bad_method|
531
- @route_set.add_route( proc { [405, { 'Allow' => allow_header, 'Content-Type' => 'text/plain' }, []]}, {
532
- :path_info => path_info,
533
- :request_method => bad_method
534
- })
535
- end
160
+ def argument_lazy?(argument)
161
+ argument.respond_to?(:lazy?) && argument.lazy?
536
162
  end
537
163
  end
538
-
539
164
  end
540
165
  end
@@ -0,0 +1,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Grape
4
+ module ContentTypes
5
+ module_function
6
+
7
+ # Content types are listed in order of preference.
8
+ DEFAULTS = {
9
+ xml: 'application/xml',
10
+ serializable_hash: 'application/json',
11
+ json: 'application/json',
12
+ binary: 'application/octet-stream',
13
+ txt: 'text/plain'
14
+ }.freeze
15
+
16
+ MIME_TYPES = Grape::ContentTypes::DEFAULTS.except(:serializable_hash).invert.freeze
17
+
18
+ def content_types_for(from_settings)
19
+ from_settings.presence || DEFAULTS
20
+ end
21
+
22
+ def mime_types_for(from_settings)
23
+ return MIME_TYPES if from_settings == Grape::ContentTypes::DEFAULTS
24
+
25
+ from_settings.invert.transform_keys! { |k| k.include?(';') ? k.split(';', 2).first : k }
26
+ end
27
+ end
28
+ end