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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +1223 -164
- data/CONTRIBUTING.md +148 -0
- data/LICENSE +1 -1
- data/README.md +3531 -675
- data/UPGRADING.md +1851 -0
- data/grape.gemspec +26 -32
- data/grape.png +0 -0
- data/lib/grape/api/instance.rb +194 -0
- data/lib/grape/api.rb +110 -485
- data/lib/grape/content_types.rb +28 -0
- data/lib/grape/cookies.rb +32 -25
- data/lib/grape/declared_params_handler.rb +118 -0
- data/lib/grape/dry_types.rb +54 -0
- data/lib/grape/dsl/callbacks.rb +19 -0
- data/lib/grape/dsl/declared.rb +35 -0
- data/lib/grape/dsl/desc.rb +65 -0
- data/lib/grape/dsl/headers.rb +21 -0
- data/lib/grape/dsl/helpers.rb +103 -0
- data/lib/grape/dsl/inside_route.rb +293 -0
- data/lib/grape/dsl/logger.rb +19 -0
- data/lib/grape/dsl/middleware.rb +36 -0
- data/lib/grape/dsl/parameters.rb +239 -0
- data/lib/grape/dsl/request_response.rb +168 -0
- data/lib/grape/dsl/routing.rb +288 -0
- data/lib/grape/dsl/settings.rb +67 -0
- data/lib/grape/dsl/validations.rb +51 -0
- data/lib/grape/endpoint.rb +287 -386
- data/lib/grape/env.rb +20 -0
- data/lib/grape/error_formatter/base.rb +56 -19
- data/lib/grape/error_formatter/json.rb +18 -7
- data/lib/grape/error_formatter/serializable_hash.rb +7 -0
- data/lib/grape/error_formatter/txt.rb +14 -11
- data/lib/grape/error_formatter/xml.rb +5 -11
- data/lib/grape/error_formatter.rb +15 -0
- data/lib/grape/exceptions/base.rb +31 -47
- data/lib/grape/exceptions/incompatible_option_values.rb +11 -0
- data/lib/grape/exceptions/invalid_accept_header.rb +11 -0
- data/lib/grape/exceptions/invalid_formatter.rb +3 -5
- data/lib/grape/exceptions/invalid_message_body.rb +11 -0
- data/lib/grape/exceptions/invalid_response.rb +11 -0
- data/lib/grape/exceptions/invalid_version_header.rb +11 -0
- data/lib/grape/exceptions/invalid_versioner_option.rb +3 -6
- data/lib/grape/exceptions/invalid_with_option_for_represent.rb +3 -7
- data/lib/grape/exceptions/method_not_allowed.rb +11 -0
- data/lib/grape/exceptions/missing_group_type.rb +11 -0
- data/lib/grape/exceptions/missing_mime_type.rb +3 -6
- data/lib/grape/exceptions/missing_vendor_option.rb +3 -5
- data/lib/grape/exceptions/request_error.rb +11 -0
- data/lib/grape/exceptions/unknown_auth_strategy.rb +11 -0
- data/lib/grape/exceptions/unknown_parameter.rb +11 -0
- data/lib/grape/exceptions/unknown_params_builder.rb +11 -0
- data/lib/grape/exceptions/unknown_validator.rb +3 -4
- data/lib/grape/exceptions/unsupported_group_type.rb +11 -0
- data/lib/grape/exceptions/validation.rb +20 -8
- data/lib/grape/exceptions/validation_array_errors.rb +14 -0
- data/lib/grape/exceptions/validation_errors.rb +59 -0
- data/lib/grape/formatter/base.rb +9 -26
- data/lib/grape/formatter/json.rb +6 -7
- data/lib/grape/formatter/serializable_hash.rb +24 -20
- data/lib/grape/formatter/txt.rb +5 -7
- data/lib/grape/formatter/xml.rb +6 -7
- data/lib/grape/formatter.rb +17 -0
- data/lib/grape/json.rb +10 -0
- data/lib/grape/locale/en.yml +47 -20
- data/lib/grape/middleware/auth/base.rb +25 -0
- data/lib/grape/middleware/auth/dsl.rb +38 -0
- data/lib/grape/middleware/auth/strategies.rb +25 -0
- data/lib/grape/middleware/auth/strategy_info.rb +15 -0
- data/lib/grape/middleware/base.rb +73 -19
- data/lib/grape/middleware/error.rb +104 -44
- data/lib/grape/middleware/filter.rb +5 -3
- data/lib/grape/middleware/formatter.rb +115 -105
- data/lib/grape/middleware/globals.rb +14 -0
- data/lib/grape/middleware/stack.rb +110 -0
- data/lib/grape/middleware/versioner/accept_version_header.rb +11 -40
- data/lib/grape/middleware/versioner/base.rb +76 -0
- data/lib/grape/middleware/versioner/header.rb +61 -78
- data/lib/grape/middleware/versioner/param.rb +9 -21
- data/lib/grape/middleware/versioner/path.rb +16 -31
- data/lib/grape/middleware/versioner.rb +10 -15
- data/lib/grape/namespace.rb +39 -10
- data/lib/grape/params_builder/base.rb +20 -0
- data/lib/grape/params_builder/hash.rb +11 -0
- data/lib/grape/params_builder/hash_with_indifferent_access.rb +11 -0
- data/lib/grape/params_builder/hashie_mash.rb +11 -0
- data/lib/grape/params_builder.rb +15 -0
- data/lib/grape/parser/base.rb +9 -24
- data/lib/grape/parser/json.rb +8 -7
- data/lib/grape/parser/xml.rb +8 -7
- data/lib/grape/parser.rb +15 -0
- data/lib/grape/path.rb +76 -0
- data/lib/grape/presenters/presenter.rb +11 -0
- data/lib/grape/railtie.rb +9 -0
- data/lib/grape/request.rb +182 -0
- data/lib/grape/router/base_route.rb +48 -0
- data/lib/grape/router/greedy_route.rb +26 -0
- data/lib/grape/router/pattern.rb +67 -0
- data/lib/grape/router/route.rb +58 -0
- data/lib/grape/router.rb +167 -0
- data/lib/grape/serve_stream/file_body.rb +36 -0
- data/lib/grape/serve_stream/sendfile_response.rb +21 -0
- data/lib/grape/serve_stream/stream_response.rb +23 -0
- data/lib/grape/util/api_description.rb +58 -0
- data/lib/grape/util/base_inheritable.rb +46 -0
- data/lib/grape/util/cache.rb +18 -0
- data/lib/grape/util/deep_freeze.rb +35 -0
- data/lib/grape/util/endpoint_configuration.rb +8 -0
- data/lib/grape/util/header.rb +13 -0
- data/lib/grape/util/inheritable_setting.rb +107 -0
- data/lib/grape/util/inheritable_values.rb +29 -0
- data/lib/grape/util/lazy/block.rb +29 -0
- data/lib/grape/util/lazy/value.rb +38 -0
- data/lib/grape/util/lazy/value_array.rb +21 -0
- data/lib/grape/util/lazy/value_enumerable.rb +34 -0
- data/lib/grape/util/lazy/value_hash.rb +21 -0
- data/lib/grape/util/media_type.rb +70 -0
- data/lib/grape/util/registry.rb +27 -0
- data/lib/grape/util/reverse_stackable_values.rb +15 -0
- data/lib/grape/util/stackable_values.rb +36 -0
- data/lib/grape/util/translation.rb +42 -0
- data/lib/grape/validations/attributes_iterator.rb +77 -0
- data/lib/grape/validations/contract_scope.rb +28 -0
- data/lib/grape/validations/multiple_attributes_iterator.rb +13 -0
- data/lib/grape/validations/param_scope_tracker.rb +57 -0
- data/lib/grape/validations/params_documentation.rb +50 -0
- data/lib/grape/validations/params_scope.rb +529 -0
- data/lib/grape/validations/single_attribute_iterator.rb +26 -0
- data/lib/grape/validations/types/array_coercer.rb +60 -0
- data/lib/grape/validations/types/custom_type_coercer.rb +164 -0
- data/lib/grape/validations/types/custom_type_collection_coercer.rb +56 -0
- data/lib/grape/validations/types/dry_type_coercer.rb +59 -0
- data/lib/grape/validations/types/file.rb +31 -0
- data/lib/grape/validations/types/invalid_value.rb +17 -0
- data/lib/grape/validations/types/json.rb +71 -0
- data/lib/grape/validations/types/multiple_type_coercer.rb +57 -0
- data/lib/grape/validations/types/primitive_coercer.rb +46 -0
- data/lib/grape/validations/types/set_coercer.rb +35 -0
- data/lib/grape/validations/types/variant_collection_coercer.rb +51 -0
- data/lib/grape/validations/types.rb +198 -0
- data/lib/grape/validations/validators/all_or_none_of_validator.rb +19 -0
- data/lib/grape/validations/validators/allow_blank_validator.rb +25 -0
- data/lib/grape/validations/validators/as_validator.rb +14 -0
- data/lib/grape/validations/validators/at_least_one_of_validator.rb +18 -0
- data/lib/grape/validations/validators/base.rb +158 -0
- data/lib/grape/validations/validators/coerce_validator.rb +55 -0
- data/lib/grape/validations/validators/contract_scope_validator.rb +45 -0
- data/lib/grape/validations/validators/default_validator.rb +31 -0
- data/lib/grape/validations/validators/exactly_one_of_validator.rb +24 -0
- data/lib/grape/validations/validators/except_values_validator.rb +33 -0
- data/lib/grape/validations/validators/length_validator.rb +48 -0
- data/lib/grape/validations/validators/multiple_params_base.rb +34 -0
- data/lib/grape/validations/validators/mutually_exclusive_validator.rb +18 -0
- data/lib/grape/validations/validators/presence_validator.rb +17 -0
- data/lib/grape/validations/validators/regexp_validator.rb +24 -0
- data/lib/grape/validations/validators/same_as_validator.rb +20 -0
- data/lib/grape/validations/validators/values_validator.rb +68 -0
- data/lib/grape/validations.rb +10 -226
- data/lib/grape/version.rb +4 -1
- data/lib/grape/xml.rb +10 -0
- data/lib/grape.rb +79 -77
- metadata +160 -306
- data/.gitignore +0 -38
- data/.rspec +0 -2
- data/.travis.yml +0 -9
- data/.yardopts +0 -2
- data/Gemfile +0 -19
- data/Guardfile +0 -15
- data/Rakefile +0 -64
- data/lib/grape/exceptions/missing_option.rb +0 -13
- data/lib/grape/exceptions/unknown_options.rb +0 -14
- data/lib/grape/http/request.rb +0 -28
- data/lib/grape/middleware/auth/basic.rb +0 -30
- data/lib/grape/middleware/auth/digest.rb +0 -30
- data/lib/grape/middleware/auth/oauth2.rb +0 -72
- data/lib/grape/route.rb +0 -23
- data/lib/grape/util/content_types.rb +0 -17
- data/lib/grape/util/deep_merge.rb +0 -23
- data/lib/grape/util/hash_stack.rb +0 -120
- data/lib/grape/validations/coerce.rb +0 -62
- data/lib/grape/validations/default.rb +0 -24
- data/lib/grape/validations/presence.rb +0 -12
- data/lib/grape/validations/regexp.rb +0 -14
- data/spec/grape/api_spec.rb +0 -2129
- data/spec/grape/endpoint_spec.rb +0 -605
- data/spec/grape/entity_spec.rb +0 -281
- data/spec/grape/exceptions/invalid_formatter_spec.rb +0 -18
- data/spec/grape/exceptions/invalid_versioner_option_spec.rb +0 -18
- data/spec/grape/exceptions/missing_mime_type_spec.rb +0 -24
- data/spec/grape/exceptions/missing_option_spec.rb +0 -18
- data/spec/grape/exceptions/unknown_options_spec.rb +0 -18
- data/spec/grape/exceptions/unknown_validator_spec.rb +0 -18
- data/spec/grape/middleware/auth/basic_spec.rb +0 -31
- data/spec/grape/middleware/auth/digest_spec.rb +0 -47
- data/spec/grape/middleware/auth/oauth2_spec.rb +0 -90
- data/spec/grape/middleware/base_spec.rb +0 -63
- data/spec/grape/middleware/error_spec.rb +0 -49
- data/spec/grape/middleware/exception_spec.rb +0 -164
- data/spec/grape/middleware/formatter_spec.rb +0 -244
- data/spec/grape/middleware/versioner/accept_version_header_spec.rb +0 -121
- data/spec/grape/middleware/versioner/header_spec.rb +0 -277
- data/spec/grape/middleware/versioner/param_spec.rb +0 -58
- data/spec/grape/middleware/versioner/path_spec.rb +0 -44
- data/spec/grape/middleware/versioner_spec.rb +0 -22
- data/spec/grape/util/hash_stack_spec.rb +0 -133
- data/spec/grape/validations/coerce_spec.rb +0 -143
- data/spec/grape/validations/default_spec.rb +0 -67
- data/spec/grape/validations/presence_spec.rb +0 -144
- data/spec/grape/validations/regexp_spec.rb +0 -33
- data/spec/grape/validations/zh-CN.yml +0 -9
- data/spec/grape/validations_spec.rb +0 -217
- data/spec/shared/versioning_examples.rb +0 -121
- data/spec/spec_helper.rb +0 -25
- data/spec/support/basic_auth_encode_helpers.rb +0 -4
- 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
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
49
|
-
instance.call(env)
|
|
16
|
+
new
|
|
50
17
|
end
|
|
18
|
+
end
|
|
51
19
|
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
#
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
#
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
#
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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
|
-
|
|
63
|
+
config
|
|
143
64
|
end
|
|
144
65
|
end
|
|
145
66
|
|
|
146
|
-
#
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
182
|
-
#
|
|
183
|
-
|
|
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
|
-
|
|
210
|
-
|
|
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
|
-
#
|
|
235
|
-
#
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
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
|
-
#
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
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
|
-
|
|
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
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
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
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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
|
-
|
|
316
|
-
|
|
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
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
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
|
|
457
|
-
|
|
458
|
-
subclass.logger = logger.clone
|
|
142
|
+
def any_lazy?(args)
|
|
143
|
+
args.any? { |argument| argument_lazy?(argument) }
|
|
459
144
|
end
|
|
460
145
|
|
|
461
|
-
def
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
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
|
-
|
|
480
|
-
|
|
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
|