skyward-api 0.1.0 → 0.2.0
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 +4 -4
- data/README.md +185 -47
- data/lib/skyward/api/assembly/application.rb +26 -0
- data/lib/skyward/api/assembly/boot.rb +533 -0
- data/lib/skyward/api/assembly/builder.rb +83 -0
- data/lib/skyward/api/assembly/dispatcher.rb +121 -0
- data/lib/skyward/api/assembly/static.rb +115 -0
- data/lib/skyward/api/assembly.rb +4 -0
- data/lib/skyward/api/cli/app_file.rb +38 -0
- data/lib/skyward/api/cli/check.rb +145 -0
- data/lib/skyward/api/cli/executable.rb +15 -0
- data/lib/skyward/api/cli/routes.rb +30 -0
- data/lib/skyward/api/cli/serve/reloader.rb +77 -0
- data/lib/skyward/api/cli/serve.rb +137 -0
- data/lib/skyward/api/cli/serve.ru +16 -0
- data/lib/skyward/api/cli.rb +4 -0
- data/lib/skyward/api/commands.rb +38 -0
- data/lib/skyward/api/endpoints/declarations.rb +124 -0
- data/lib/skyward/api/endpoints/helpers.rb +49 -0
- data/lib/skyward/api/endpoints/route.rb +13 -0
- data/lib/skyward/api/endpoints.rb +4 -0
- data/lib/skyward/api/inputs/coercer.rb +425 -0
- data/lib/skyward/api/inputs.rb +164 -0
- data/lib/skyward/api/middleware/line_logger.rb +20 -0
- data/lib/skyward/api/middleware/request_id.rb +26 -0
- data/lib/skyward/api/middleware/request_log.rb +46 -0
- data/lib/skyward/api/middleware/rescue.rb +81 -0
- data/lib/skyward/api/middleware.rb +4 -0
- data/lib/skyward/api/openapi/docs.rb +39 -0
- data/lib/skyward/api/openapi.rb +393 -0
- data/lib/skyward/api/request.rb +127 -0
- data/lib/skyward/api/responses/bad_request.rb +18 -0
- data/lib/skyward/api/responses/conflict.rb +18 -0
- data/lib/skyward/api/responses/created.rb +19 -0
- data/lib/skyward/api/responses/forbidden.rb +18 -0
- data/lib/skyward/api/responses/no_content.rb +13 -0
- data/lib/skyward/api/responses/not_found.rb +18 -0
- data/lib/skyward/api/responses/redirect.rb +25 -0
- data/lib/skyward/api/responses/unauthorized.rb +18 -0
- data/lib/skyward/api/responses/unprocessable.rb +18 -0
- data/lib/skyward/api/responses.rb +4 -0
- data/lib/skyward/api/return_type_error.rb +4 -0
- data/lib/skyward/api/routing/percent_encoding.rb +15 -0
- data/lib/skyward/api/routing/router.rb +115 -0
- data/lib/skyward/api/routing.rb +4 -0
- data/lib/skyward/api/serializer/writers.rb +230 -0
- data/lib/skyward/api/serializer.rb +139 -0
- data/lib/skyward/api/test/client.rb +160 -0
- data/lib/skyward/api/test.rb +8 -0
- data/lib/skyward/api/version.rb +5 -1
- data/lib/skyward/api.rb +118 -1
- data/sig/generated/skyward/api/assembly/application.rbs +22 -0
- data/sig/generated/skyward/api/assembly/boot.rbs +217 -0
- data/sig/generated/skyward/api/assembly/builder.rbs +77 -0
- data/sig/generated/skyward/api/assembly/dispatcher.rbs +84 -0
- data/sig/generated/skyward/api/assembly/static.rbs +47 -0
- data/sig/generated/skyward/api/assembly.rbs +4 -0
- data/sig/generated/skyward/api/cli/app_file.rbs +15 -0
- data/sig/generated/skyward/api/cli/check.rbs +76 -0
- data/sig/generated/skyward/api/cli/executable.rbs +11 -0
- data/sig/generated/skyward/api/cli/routes.rbs +19 -0
- data/sig/generated/skyward/api/cli/serve/reloader.rbs +46 -0
- data/sig/generated/skyward/api/cli/serve.rbs +56 -0
- data/sig/generated/skyward/api/cli.rbs +4 -0
- data/sig/generated/skyward/api/commands.rbs +2 -0
- data/sig/generated/skyward/api/endpoints/declarations.rbs +81 -0
- data/sig/generated/skyward/api/endpoints/helpers.rbs +49 -0
- data/sig/generated/skyward/api/endpoints/route.rbs +24 -0
- data/sig/generated/skyward/api/endpoints.rbs +4 -0
- data/sig/generated/skyward/api/inputs/coercer.rbs +231 -0
- data/sig/generated/skyward/api/inputs.rbs +75 -0
- data/sig/generated/skyward/api/middleware/line_logger.rbs +13 -0
- data/sig/generated/skyward/api/middleware/request_id.rbs +17 -0
- data/sig/generated/skyward/api/middleware/request_log.rbs +18 -0
- data/sig/generated/skyward/api/middleware/rescue.rbs +41 -0
- data/sig/generated/skyward/api/middleware.rbs +4 -0
- data/sig/generated/skyward/api/openapi/docs.rbs +17 -0
- data/sig/generated/skyward/api/openapi.rbs +198 -0
- data/sig/generated/skyward/api/request.rbs +65 -0
- data/sig/generated/skyward/api/responses/bad_request.rbs +14 -0
- data/sig/generated/skyward/api/responses/conflict.rbs +14 -0
- data/sig/generated/skyward/api/responses/created.rbs +15 -0
- data/sig/generated/skyward/api/responses/forbidden.rbs +14 -0
- data/sig/generated/skyward/api/responses/no_content.rbs +10 -0
- data/sig/generated/skyward/api/responses/not_found.rbs +14 -0
- data/sig/generated/skyward/api/responses/redirect.rbs +20 -0
- data/sig/generated/skyward/api/responses/unauthorized.rbs +14 -0
- data/sig/generated/skyward/api/responses/unprocessable.rbs +14 -0
- data/sig/generated/skyward/api/responses.rbs +4 -0
- data/sig/generated/skyward/api/return_type_error.rbs +4 -0
- data/sig/generated/skyward/api/routing/percent_encoding.rbs +11 -0
- data/sig/generated/skyward/api/routing/router.rbs +158 -0
- data/sig/generated/skyward/api/routing.rbs +4 -0
- data/sig/generated/skyward/api/serializer/writers.rbs +126 -0
- data/sig/generated/skyward/api/serializer.rbs +79 -0
- data/sig/generated/skyward/api/test/client.rbs +117 -0
- data/sig/generated/skyward/api/test.rbs +6 -0
- data/sig/generated/skyward/api.rbs +38 -0
- data/sig/manual/skyward/api/assembly/boot.rbs +3 -0
- data/sig/manual/skyward/api/cli/app_file.rbs +3 -0
- data/sig/manual/skyward/api/cli/check.rbs +3 -0
- data/sig/manual/skyward/api/cli/executable.rbs +3 -0
- data/sig/manual/skyward/api/cli/routes.rbs +3 -0
- data/sig/manual/skyward/api/cli/serve.rbs +3 -0
- data/sig/manual/skyward/api/inputs/coercer.rbs +3 -0
- data/sig/manual/skyward/api/openapi/docs.rbs +3 -0
- data/sig/manual/skyward/api/openapi.rbs +3 -0
- data/sig/manual/skyward/api/routing/percent_encoding.rbs +3 -0
- data/sig/manual/skyward/api/serializer/writers.rbs +3 -0
- data/sig/manual/skyward/api/test.rbs +3 -0
- data/sig/manual/skyward/api.rbs +21 -0
- data/sig/manual/zeitwerk/loader.rbs +6 -0
- metadata +110 -3
|
@@ -0,0 +1,533 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Skyward::API::Assembly::Boot
|
|
4
|
+
extend self
|
|
5
|
+
|
|
6
|
+
UNNAMED = %i[req opt rest keyrest].freeze #: Array[Symbol]
|
|
7
|
+
|
|
8
|
+
KEYWORD = %i[keyreq key].freeze #: Array[Symbol]
|
|
9
|
+
|
|
10
|
+
RACK = ["::Skyward::API::rack", "[::Integer, ::Hash[::String, ::String], untyped]"].map do |type|
|
|
11
|
+
RBS::Parser.parse_type(type)
|
|
12
|
+
end.freeze #: Array[RBS::Types::t?]
|
|
13
|
+
|
|
14
|
+
REQUEST = RBS::Parser.parse_type("::Skyward::API::Request") #: RBS::Types::t?
|
|
15
|
+
|
|
16
|
+
REQUEST_TYPE = Skyward::Core::Types::Named.new(
|
|
17
|
+
name: "Skyward::API::Request",
|
|
18
|
+
klass: Skyward::API::Request,
|
|
19
|
+
fields: []
|
|
20
|
+
) #: Skyward::Core::Types::Named
|
|
21
|
+
|
|
22
|
+
# A method with no signature is read as if each keyword and the return were
|
|
23
|
+
# untyped, which is what rbs-inline writes for a method with no annotations.
|
|
24
|
+
ANY = RBS::Types::Bases::Any.new(location: nil) #: RBS::Types::Bases::Any
|
|
25
|
+
|
|
26
|
+
# @rbs (Array[Skyward::API::Assembly::Builder::Mount] mounts,
|
|
27
|
+
# providers: Hash[Symbol, Skyward::API::_Provider & Object], reader: Skyward::Core::Types::Reader,
|
|
28
|
+
# max_body_size: Integer, strict: bool) ->
|
|
29
|
+
# Array[Skyward::API::Routing::Router::Endpoint]
|
|
30
|
+
def endpoints(mounts, providers:, reader:, max_body_size:, strict:)
|
|
31
|
+
single = providers.filter_map { |name, callable| single_object(name, callable) }.first
|
|
32
|
+
raise Skyward::Core::BootError, single if single
|
|
33
|
+
|
|
34
|
+
provided = providers.to_h { |name, callable| [name, provider(name, callable, reader)] }
|
|
35
|
+
none = [] #: Array[Skyward::API::Routing::Router::Endpoint]
|
|
36
|
+
built = mounts.reduce(none) do |booted, mount|
|
|
37
|
+
mount.api.class.routes.reduce(booted) do |so_far, route|
|
|
38
|
+
[*so_far, boot(mount, route, so_far, provided, reader, max_body_size)]
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
return built unless strict
|
|
42
|
+
|
|
43
|
+
refused = built.filter_map { |endpoint| untyped(endpoint, reader) }
|
|
44
|
+
raise Skyward::Core::BootError, refused.join("\n") unless refused.empty?
|
|
45
|
+
|
|
46
|
+
built
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
private
|
|
50
|
+
|
|
51
|
+
# @rbs (Skyward::API::_Provider & Object callable) -> Method
|
|
52
|
+
def call_method(callable) = callable.is_a?(Method) ? callable : callable.method(:call)
|
|
53
|
+
|
|
54
|
+
# The reader finds a signature only for an instance method of a class.
|
|
55
|
+
# @rbs (Symbol name, Skyward::API::_Provider & Object callable) -> String?
|
|
56
|
+
def single_object(name, callable)
|
|
57
|
+
method = call_method(callable)
|
|
58
|
+
return unless method.receiver.is_a?(Module) || method.owner.singleton_class?
|
|
59
|
+
|
|
60
|
+
"The :#{name} provider's `#{method.name}` is defined on a single object, such as a module or a class, " \
|
|
61
|
+
"and Skyward API can't read the signature of those. Provide an instance of a class."
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
# @rbs (Symbol name, Skyward::API::_Provider & Object callable, Skyward::Core::Types::Reader reader) ->
|
|
65
|
+
# Skyward::API::Routing::Router::Provider
|
|
66
|
+
def provider(name, callable, reader)
|
|
67
|
+
label = "The :#{name} provider"
|
|
68
|
+
method = call_method(callable)
|
|
69
|
+
# A method is signed by the module that defines it, which isn't always its receiver's class.
|
|
70
|
+
returned = signature(method.owner, method.name, reader)&.type&.return_type
|
|
71
|
+
if returned.nil? || returned.is_a?(RBS::Types::Bases::Any)
|
|
72
|
+
serializer = Skyward::API::Serializer.new([Skyward::API::Serializer::UNTYPED], label:)
|
|
73
|
+
return Skyward::API::Routing::Router::Provider.new(name:, callable:, value: nil, responses: [], serializer:)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
parts = parts(returned)
|
|
77
|
+
responses = parts.filter_map { |part| response_value(part) }
|
|
78
|
+
value = parts.reject { |part| response_value(part) }
|
|
79
|
+
serializer = Skyward::API::Serializer.new(responses, label:)
|
|
80
|
+
Skyward::API::Routing::Router::Provider.new(name:, callable:, value:, responses:, serializer:)
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# @rbs mount: Skyward::API::Assembly::Builder::Mount
|
|
84
|
+
# @rbs route: Skyward::API::Endpoints::Route
|
|
85
|
+
# @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
|
|
86
|
+
# @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
|
|
87
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
88
|
+
# @rbs max_body_size: Integer
|
|
89
|
+
# @rbs return: Skyward::API::Routing::Router::Endpoint
|
|
90
|
+
def boot(mount, route, built, providers, reader, max_body_size)
|
|
91
|
+
path = full_path(mount.at, route.path)
|
|
92
|
+
verb = route.verb.upcase.name
|
|
93
|
+
pattern = pattern(path)
|
|
94
|
+
label = "#{mount.api.class}##{route.to} (#{verb} #{path})"
|
|
95
|
+
result = summary(route) || shadowing(verb, pattern, built) ||
|
|
96
|
+
endpoint(mount.api, route, verb, pattern, label, providers, reader, max_body_size)
|
|
97
|
+
case result
|
|
98
|
+
when String then raise Skyward::Core::BootError, "#{label}\n #{result}"
|
|
99
|
+
else result
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
# @rbs route: Skyward::API::Endpoints::Route
|
|
104
|
+
# @rbs return: String?
|
|
105
|
+
def summary(route)
|
|
106
|
+
return unless route.summary&.match?(/\R/)
|
|
107
|
+
|
|
108
|
+
"Its summary: has a line break, but a summary is one line. Put the rest in description:."
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
# @rbs prefix: String
|
|
112
|
+
# @rbs path: String
|
|
113
|
+
# @rbs return: String
|
|
114
|
+
def full_path(prefix, path)
|
|
115
|
+
parts = [prefix, path].map { |part| part.delete_prefix("/").delete_suffix("/") }
|
|
116
|
+
"/#{parts.reject(&:empty?).join("/")}"
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
# @rbs path: String
|
|
120
|
+
# @rbs return: Array[String | Symbol]
|
|
121
|
+
def pattern(path)
|
|
122
|
+
path.split("/", -1).map { |segment| segment.start_with?(":") ? segment.delete_prefix(":").to_sym : segment }
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
# @rbs verb: String
|
|
126
|
+
# @rbs pattern: Array[String | Symbol]
|
|
127
|
+
# @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
|
|
128
|
+
# @rbs return: String?
|
|
129
|
+
def shadowing(verb, pattern, built)
|
|
130
|
+
earlier = built.find { |endpoint| endpoint.verb == verb && covers?(endpoint.pattern, pattern) }
|
|
131
|
+
return unless earlier
|
|
132
|
+
|
|
133
|
+
if covers?(pattern, earlier.pattern)
|
|
134
|
+
"#{earlier.label} is tried first and matches exactly the same paths, so this route is never reached. " \
|
|
135
|
+
"Remove one of them, or change a path."
|
|
136
|
+
else
|
|
137
|
+
"#{earlier.label} is tried first and matches every path this route does, so this route is never reached. " \
|
|
138
|
+
"Declare the static route first."
|
|
139
|
+
end
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
# A path parameter matches any segment but an empty one, which only the root path has.
|
|
143
|
+
# @rbs pattern: Array[String | Symbol]
|
|
144
|
+
# @rbs other: Array[String | Symbol]
|
|
145
|
+
# @rbs return: bool
|
|
146
|
+
def covers?(pattern, other)
|
|
147
|
+
pattern.length == other.length &&
|
|
148
|
+
pattern.zip(other).all? { |part, other_part| part == other_part || (part.is_a?(Symbol) && other_part != "") }
|
|
149
|
+
end
|
|
150
|
+
|
|
151
|
+
# @rbs api: Skyward::API
|
|
152
|
+
# @rbs route: Skyward::API::Endpoints::Route
|
|
153
|
+
# @rbs verb: String
|
|
154
|
+
# @rbs pattern: Array[String | Symbol]
|
|
155
|
+
# @rbs label: String
|
|
156
|
+
# @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
|
|
157
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
158
|
+
# @rbs max_body_size: Integer
|
|
159
|
+
# @rbs return: Skyward::API::Routing::Router::Endpoint | String
|
|
160
|
+
def endpoint(api, route, verb, pattern, label, providers, reader, max_body_size)
|
|
161
|
+
method_type = method_type(api.class, route.to, reader)
|
|
162
|
+
return method_type if method_type.is_a?(String)
|
|
163
|
+
|
|
164
|
+
function = method_type&.type
|
|
165
|
+
signed = signed(api.class.instance_method(route.to).parameters, function)
|
|
166
|
+
return signed if signed.is_a?(String)
|
|
167
|
+
|
|
168
|
+
unnamed = pattern.grep(Symbol).find { |name| signed.none? { |keyword, _, _| keyword == name } }
|
|
169
|
+
if unnamed
|
|
170
|
+
return "The route has a path parameter :#{unnamed}, but the method has no `#{unnamed}:` keyword. " \
|
|
171
|
+
"Add `#{unnamed}:` to the method, or rename the path parameter."
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
both = pattern.grep(Symbol).find { |name| providers.key?(name) }
|
|
175
|
+
if both
|
|
176
|
+
return "The route has a path parameter :#{both}, but :#{both} is provided too, so `#{both}:` can't be both. " \
|
|
177
|
+
"Rename the path parameter, or provide another name."
|
|
178
|
+
end
|
|
179
|
+
|
|
180
|
+
read = signed.map { |name, required, type| keyword(name, required, type, pattern, providers, reader) }
|
|
181
|
+
problem = read.find { |keyword| keyword.is_a?(String) }
|
|
182
|
+
return problem if problem.is_a?(String)
|
|
183
|
+
|
|
184
|
+
keywords = read.grep(Skyward::API::Routing::Router::Keyword) #: Array[Skyward::API::Routing::Router::Keyword]
|
|
185
|
+
provided = read.grep(Skyward::API::Routing::Router::Provider) #: Array[Skyward::API::Routing::Router::Provider]
|
|
186
|
+
|
|
187
|
+
returns = returns(function&.return_type || ANY, reader)
|
|
188
|
+
return returns if returns.is_a?(String)
|
|
189
|
+
|
|
190
|
+
inputs = Skyward::API::Inputs.new(keywords, providers: provided, max_body_size:)
|
|
191
|
+
serializer = Skyward::API::Serializer.new(returns, label:)
|
|
192
|
+
Skyward::API::Routing::Router::Endpoint.new(
|
|
193
|
+
verb:,
|
|
194
|
+
pattern:,
|
|
195
|
+
api:,
|
|
196
|
+
to: route.to,
|
|
197
|
+
label:,
|
|
198
|
+
summary: route.summary,
|
|
199
|
+
description: route.description,
|
|
200
|
+
keywords:,
|
|
201
|
+
providers: provided,
|
|
202
|
+
returns:,
|
|
203
|
+
signature: written_signature(method_type || unannotated(signed)),
|
|
204
|
+
inputs:,
|
|
205
|
+
serializer:
|
|
206
|
+
)
|
|
207
|
+
# The reader raises for a type it can't read at all, such as one that refers
|
|
208
|
+
# to itself, and that's this route's problem too.
|
|
209
|
+
rescue Skyward::Core::BootError => e
|
|
210
|
+
e.message
|
|
211
|
+
end
|
|
212
|
+
|
|
213
|
+
# @rbs klass: Class
|
|
214
|
+
# @rbs to: Symbol
|
|
215
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
216
|
+
# @rbs return: RBS::MethodType | String | nil
|
|
217
|
+
def method_type(klass, to, reader)
|
|
218
|
+
unless klass.public_method_defined?(to)
|
|
219
|
+
return "#{klass} has no public method `#{to}`. Define it as a public method, or change to:."
|
|
220
|
+
end
|
|
221
|
+
|
|
222
|
+
signature(klass, to, reader)
|
|
223
|
+
end
|
|
224
|
+
|
|
225
|
+
# @rbs owner: Module
|
|
226
|
+
# @rbs name: Symbol
|
|
227
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
228
|
+
# @rbs return: RBS::MethodType?
|
|
229
|
+
def signature(owner, name, reader)
|
|
230
|
+
type_name = reader.type_name(owner)
|
|
231
|
+
reader.method_type(type_name, name) if type_name
|
|
232
|
+
end
|
|
233
|
+
|
|
234
|
+
# @rbs parameters: Method::param_types
|
|
235
|
+
# @rbs type: RBS::Types::function?
|
|
236
|
+
# @rbs return: Array[[Symbol, bool, RBS::Types::t]] | String
|
|
237
|
+
def signed(parameters, type)
|
|
238
|
+
if parameters.any? { |kind, _| UNNAMED.include?(kind) }
|
|
239
|
+
return "The method takes positional arguments or **rest, but Skyward API passes only named keywords. " \
|
|
240
|
+
"Take each input as a keyword, such as `id:`."
|
|
241
|
+
end
|
|
242
|
+
|
|
243
|
+
keywords = parameters.filter_map { |kind, name| [name, kind == :keyreq] if KEYWORD.include?(kind) }.to_h
|
|
244
|
+
return keywords.map { |name, required| [name, required, ANY] } unless type
|
|
245
|
+
|
|
246
|
+
function = keyword_only(type)
|
|
247
|
+
return stale(keywords, type) unless function && keyword_requirements(function) == keywords
|
|
248
|
+
|
|
249
|
+
params = function.required_keywords.merge(function.optional_keywords)
|
|
250
|
+
keywords.map { |name, required| [name, required, params.fetch(name).type] }
|
|
251
|
+
end
|
|
252
|
+
|
|
253
|
+
# @rbs method_type: RBS::MethodType
|
|
254
|
+
# @rbs return: String
|
|
255
|
+
def written_signature(method_type) = method_type.location&.source || method_type.to_s
|
|
256
|
+
|
|
257
|
+
# @rbs signed: Array[[Symbol, bool, RBS::Types::t]]
|
|
258
|
+
# @rbs return: RBS::MethodType
|
|
259
|
+
def unannotated(signed)
|
|
260
|
+
params = signed.to_h { |name, _, type| [name, RBS::Types::Function::Param.new(type:, name: nil)] }
|
|
261
|
+
required = signed.filter_map { |name, needed, _| name if needed }
|
|
262
|
+
function = RBS::Types::Function.empty(ANY).update(
|
|
263
|
+
required_keywords: params.slice(*required),
|
|
264
|
+
optional_keywords: params.except(*required)
|
|
265
|
+
)
|
|
266
|
+
RBS::MethodType.new(type_params: [], type: function, block: nil, location: nil)
|
|
267
|
+
end
|
|
268
|
+
|
|
269
|
+
# @rbs keywords: Hash[Symbol, bool]
|
|
270
|
+
# @rbs function: RBS::Types::function
|
|
271
|
+
# @rbs return: String
|
|
272
|
+
def stale(keywords, function)
|
|
273
|
+
taken = keywords.map { |name, required| "#{"?" unless required}#{name}:" }
|
|
274
|
+
"The method takes (#{taken.join(", ")}), but its signature takes (#{written(function.param_to_s)}), " \
|
|
275
|
+
"so the signature is stale. Run rbs-inline, or update the signature."
|
|
276
|
+
end
|
|
277
|
+
|
|
278
|
+
# @rbs function: RBS::Types::function
|
|
279
|
+
# @rbs return: RBS::Types::Function?
|
|
280
|
+
def keyword_only(function)
|
|
281
|
+
case function
|
|
282
|
+
when RBS::Types::Function
|
|
283
|
+
others = [
|
|
284
|
+
*function.required_positionals,
|
|
285
|
+
*function.optional_positionals,
|
|
286
|
+
*function.trailing_positionals,
|
|
287
|
+
function.rest_positionals,
|
|
288
|
+
function.rest_keywords
|
|
289
|
+
]
|
|
290
|
+
function if others.compact.empty?
|
|
291
|
+
end
|
|
292
|
+
end
|
|
293
|
+
|
|
294
|
+
# @rbs function: RBS::Types::Function
|
|
295
|
+
# @rbs return: Hash[Symbol, bool]
|
|
296
|
+
def keyword_requirements(function)
|
|
297
|
+
function.required_keywords.transform_values { true }.merge(function.optional_keywords.transform_values { false })
|
|
298
|
+
end
|
|
299
|
+
|
|
300
|
+
# @rbs name: Symbol
|
|
301
|
+
# @rbs required: bool
|
|
302
|
+
# @rbs type: RBS::Types::t
|
|
303
|
+
# @rbs pattern: Array[String | Symbol]
|
|
304
|
+
# @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
|
|
305
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
306
|
+
# @rbs return: Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | String
|
|
307
|
+
def keyword(name, required, type, pattern, providers, reader)
|
|
308
|
+
source = source(name, pattern)
|
|
309
|
+
return request(required, type) if source == :request
|
|
310
|
+
|
|
311
|
+
provider = providers[name]
|
|
312
|
+
return provided(name, type, provider) if provider
|
|
313
|
+
|
|
314
|
+
read = reader.read(type)
|
|
315
|
+
case read
|
|
316
|
+
when Skyward::Core::Types::Unreadable then unreadable("The type of `#{name}:`", read)
|
|
317
|
+
else
|
|
318
|
+
carried(name, source, read) || Skyward::API::Routing::Router::Keyword.new(name:, source:, required:, type: read)
|
|
319
|
+
end
|
|
320
|
+
end
|
|
321
|
+
|
|
322
|
+
# @rbs name: Symbol
|
|
323
|
+
# @rbs pattern: Array[String | Symbol]
|
|
324
|
+
# @rbs return: :path | :query | :body | :request
|
|
325
|
+
def source(name, pattern)
|
|
326
|
+
if pattern.include?(name) then :path
|
|
327
|
+
elsif name == :body then :body
|
|
328
|
+
elsif name == :request then :request
|
|
329
|
+
else :query
|
|
330
|
+
end
|
|
331
|
+
end
|
|
332
|
+
|
|
333
|
+
# @rbs required: bool
|
|
334
|
+
# @rbs type: RBS::Types::t
|
|
335
|
+
# @rbs return: Skyward::API::Routing::Router::Keyword | String
|
|
336
|
+
def request(required, type)
|
|
337
|
+
unless [REQUEST, ANY].include?(type)
|
|
338
|
+
return "`request:` is always the Skyward::API::Request, but its signature types it as #{written(type.to_s)}. " \
|
|
339
|
+
"Type it as Skyward::API::Request, or rename the keyword."
|
|
340
|
+
end
|
|
341
|
+
|
|
342
|
+
Skyward::API::Routing::Router::Keyword.new(name: :request, source: :request, required:, type: REQUEST_TYPE)
|
|
343
|
+
end
|
|
344
|
+
|
|
345
|
+
# A provided keyword's type is the provider's to give, so it's compared, never
|
|
346
|
+
# read, except that an untyped keyword is left unchecked, as untyped code is.
|
|
347
|
+
# @rbs name: Symbol
|
|
348
|
+
# @rbs type: RBS::Types::t
|
|
349
|
+
# @rbs provider: Skyward::API::Routing::Router::Provider
|
|
350
|
+
# @rbs return: Skyward::API::Routing::Router::Provider | String
|
|
351
|
+
def provided(name, type, provider)
|
|
352
|
+
value = provider.value
|
|
353
|
+
return provider if value.nil? || untyped_type?(type) || same?(parts(type), value)
|
|
354
|
+
|
|
355
|
+
returned = value.empty? ? "only responses" : "#{written(value.join(" | "))}, besides any responses"
|
|
356
|
+
"`#{name}:` is typed as #{written(type.to_s)}, but the :#{name} provider returns #{returned}. " \
|
|
357
|
+
"Give them the same type."
|
|
358
|
+
end
|
|
359
|
+
|
|
360
|
+
# @rbs type: RBS::Types::t
|
|
361
|
+
# @rbs return: bool
|
|
362
|
+
def untyped_type?(type) = parts(type).grep_v(RBS::Types::Bases::Nil) == [ANY]
|
|
363
|
+
|
|
364
|
+
# A union means the same in any order.
|
|
365
|
+
# @rbs types: Array[RBS::Types::t]
|
|
366
|
+
# @rbs others: Array[RBS::Types::t]
|
|
367
|
+
# @rbs return: bool
|
|
368
|
+
def same?(types, others) = (types - others).empty? && (others - types).empty?
|
|
369
|
+
|
|
370
|
+
# @rbs name: Symbol
|
|
371
|
+
# @rbs source: :path | :query | :body | :request
|
|
372
|
+
# @rbs type: Skyward::Core::Types::t
|
|
373
|
+
# @rbs return: String?
|
|
374
|
+
def carried(name, source, type)
|
|
375
|
+
case source
|
|
376
|
+
when :path
|
|
377
|
+
uncarried = uncarried(type, :path)
|
|
378
|
+
if uncarried
|
|
379
|
+
"`#{name}:` comes from the path, which can't carry #{uncarried}. " \
|
|
380
|
+
"Give it a type such as String, Integer or an enum."
|
|
381
|
+
end
|
|
382
|
+
when :query
|
|
383
|
+
uncarried = uncarried(type, :query)
|
|
384
|
+
if uncarried
|
|
385
|
+
"`#{name}:` comes from the query string, which can't carry #{uncarried}. " \
|
|
386
|
+
"Give it a type such as String, Integer or an array of them, or take it in `body:`."
|
|
387
|
+
end
|
|
388
|
+
end
|
|
389
|
+
end
|
|
390
|
+
|
|
391
|
+
# @rbs type: Skyward::Core::Types::t
|
|
392
|
+
# @rbs within: :path | :query | :array
|
|
393
|
+
# @rbs return: String?
|
|
394
|
+
def uncarried(type, within)
|
|
395
|
+
case type
|
|
396
|
+
when Skyward::Core::Types::Record then "a record"
|
|
397
|
+
when Skyward::Core::Types::HashOf then "a hash"
|
|
398
|
+
when Skyward::Core::Types::Named then "#{type.name}, a class"
|
|
399
|
+
when Skyward::Core::Types::ArrayOf
|
|
400
|
+
case within
|
|
401
|
+
when :path then "an array"
|
|
402
|
+
when :query then uncarried(type.type, :array)
|
|
403
|
+
else "an array of arrays"
|
|
404
|
+
end
|
|
405
|
+
when Skyward::Core::Types::Nullable then uncarried(type.type, within)
|
|
406
|
+
when Skyward::Core::Types::Union then type.types.lazy.filter_map { |member| uncarried(member, within) }.first
|
|
407
|
+
end
|
|
408
|
+
end
|
|
409
|
+
|
|
410
|
+
# Response values are found in the signature, because the reader can't read them.
|
|
411
|
+
# @rbs type: RBS::Types::t
|
|
412
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
413
|
+
# @rbs return: Array[Skyward::API::Routing::Router::returned] | String
|
|
414
|
+
def returns(type, reader)
|
|
415
|
+
read = parts(type).map { |part| response(part, reader) || reader.read(part) }
|
|
416
|
+
unreadable = read.find { |member| member.is_a?(Skyward::Core::Types::Unreadable) }
|
|
417
|
+
return unreadable("The return type", unreadable) if unreadable.is_a?(Skyward::Core::Types::Unreadable)
|
|
418
|
+
|
|
419
|
+
readable = read.grep_v(Skyward::Core::Types::Unreadable) #: Array[Skyward::API::Routing::Router::returned]
|
|
420
|
+
readable.flat_map { |member| members(member) }.uniq
|
|
421
|
+
end
|
|
422
|
+
|
|
423
|
+
# @rbs type: RBS::Types::t
|
|
424
|
+
# @rbs return: Array[RBS::Types::t]
|
|
425
|
+
def parts(type)
|
|
426
|
+
case type
|
|
427
|
+
when RBS::Types::Union then type.types.flat_map { |member| parts(member) }
|
|
428
|
+
when RBS::Types::Optional then [*parts(type.type), RBS::Types::Bases::Nil.new(location: nil)]
|
|
429
|
+
else [type]
|
|
430
|
+
end
|
|
431
|
+
end
|
|
432
|
+
|
|
433
|
+
# @rbs type: RBS::Types::t
|
|
434
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
435
|
+
# @rbs return: Skyward::API::Routing::Router::Created | Skyward::API::Routing::Router::Response | Skyward::API::Routing::Router::Rack
|
|
436
|
+
# | Skyward::Core::Types::Unreadable | nil
|
|
437
|
+
def response(type, reader)
|
|
438
|
+
return Skyward::API::Routing::Router::Rack.new if RACK.include?(type)
|
|
439
|
+
if type.is_a?(RBS::Types::ClassInstance) && type.name.to_s == "::Skyward::API::Responses::Created"
|
|
440
|
+
return created(type, reader)
|
|
441
|
+
end
|
|
442
|
+
|
|
443
|
+
response_value(type)
|
|
444
|
+
end
|
|
445
|
+
|
|
446
|
+
# @rbs type: RBS::Types::t
|
|
447
|
+
# @rbs return: Skyward::API::Routing::Router::Response?
|
|
448
|
+
def response_value(type)
|
|
449
|
+
return unless type.is_a?(RBS::Types::ClassInstance)
|
|
450
|
+
|
|
451
|
+
klass = Skyward::API::Serializer::RESPONSES.find { |response| type.name.to_s == "::#{response.name}" }
|
|
452
|
+
Skyward::API::Routing::Router::Response.new(klass:) if klass
|
|
453
|
+
end
|
|
454
|
+
|
|
455
|
+
# @rbs type: RBS::Types::ClassInstance
|
|
456
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
457
|
+
# @rbs return: Skyward::API::Routing::Router::Created | Skyward::Core::Types::Unreadable
|
|
458
|
+
def created(type, reader)
|
|
459
|
+
unless type.args.size == 1
|
|
460
|
+
return Skyward::Core::Types::Unreadable.new(type: written(type.to_s), at: nil, instead: "Skyward::API::Responses::Created[T]")
|
|
461
|
+
end
|
|
462
|
+
|
|
463
|
+
read = reader.read(type.args.fetch(0))
|
|
464
|
+
case read
|
|
465
|
+
when Skyward::Core::Types::Unreadable then read
|
|
466
|
+
else Skyward::API::Routing::Router::Created.new(type: read)
|
|
467
|
+
end
|
|
468
|
+
end
|
|
469
|
+
|
|
470
|
+
# @rbs type: Skyward::API::Routing::Router::returned
|
|
471
|
+
# @rbs return: Array[Skyward::API::Routing::Router::returned]
|
|
472
|
+
def members(type)
|
|
473
|
+
case type
|
|
474
|
+
when Skyward::Core::Types::Union then type.types
|
|
475
|
+
when Skyward::Core::Types::Nullable then [*members(type.type), Skyward::Core::Types::Reader::NIL_LITERAL]
|
|
476
|
+
else [type]
|
|
477
|
+
end
|
|
478
|
+
end
|
|
479
|
+
|
|
480
|
+
# @rbs endpoint: Skyward::API::Routing::Router::Endpoint
|
|
481
|
+
# @rbs reader: Skyward::Core::Types::Reader
|
|
482
|
+
# @rbs return: String?
|
|
483
|
+
def untyped(endpoint, reader)
|
|
484
|
+
method_type = signature(endpoint.api.class, endpoint.to, reader)
|
|
485
|
+
function = keyword_only(method_type.type) if method_type
|
|
486
|
+
problem =
|
|
487
|
+
if function
|
|
488
|
+
untyped_parts(endpoint, function)
|
|
489
|
+
else
|
|
490
|
+
"It has no RBS signature, but strict: true refuses an untyped endpoint. " \
|
|
491
|
+
"Annotate it and run rbs-inline, or check `signatures:`."
|
|
492
|
+
end
|
|
493
|
+
"#{endpoint.label}\n #{problem}" if problem
|
|
494
|
+
end
|
|
495
|
+
|
|
496
|
+
# Only a keyword's whole type, nullable or not, or a member of the return type
|
|
497
|
+
# counts, so strict: true lets through untyped inside a type, as in Array[untyped].
|
|
498
|
+
# @rbs endpoint: Skyward::API::Routing::Router::Endpoint
|
|
499
|
+
# @rbs function: RBS::Types::Function
|
|
500
|
+
# @rbs return: String?
|
|
501
|
+
def untyped_parts(endpoint, function)
|
|
502
|
+
any = Skyward::API::Serializer::UNTYPED
|
|
503
|
+
keywords = endpoint.keywords.filter_map do |keyword|
|
|
504
|
+
type = keyword.type
|
|
505
|
+
"`#{keyword.name}:`" if (type.is_a?(Skyward::Core::Types::Nullable) ? type.type : type) == any
|
|
506
|
+
end
|
|
507
|
+
# A provided keyword's type is never read, so it's found in the signature.
|
|
508
|
+
params = function.required_keywords.merge(function.optional_keywords)
|
|
509
|
+
provided = endpoint.providers.filter_map do |provider|
|
|
510
|
+
"`#{provider.name}:`" if untyped_type?(params.fetch(provider.name).type)
|
|
511
|
+
end
|
|
512
|
+
named = [*keywords, *provided]
|
|
513
|
+
found = endpoint.returns.include?(any) ? [*named, "the return type"] : named
|
|
514
|
+
return if found.empty?
|
|
515
|
+
|
|
516
|
+
*rest, last = found
|
|
517
|
+
listed = rest.empty? ? last : "#{rest.join(", ")} and #{last}"
|
|
518
|
+
"Its signature leaves #{listed} untyped, but strict: true refuses an untyped endpoint. " \
|
|
519
|
+
"Give #{found.one? ? "it" : "each"} a type."
|
|
520
|
+
end
|
|
521
|
+
|
|
522
|
+
# @rbs subject: String
|
|
523
|
+
# @rbs type: Skyward::Core::Types::Unreadable
|
|
524
|
+
# @rbs return: String
|
|
525
|
+
def unreadable(subject, type)
|
|
526
|
+
"#{subject} can't be read: Skyward API doesn't read #{type.type}#{", at #{type.at}" if type.at}. " \
|
|
527
|
+
"Use #{type.instead} instead."
|
|
528
|
+
end
|
|
529
|
+
|
|
530
|
+
# @rbs text: String
|
|
531
|
+
# @rbs return: String
|
|
532
|
+
def written(text) = text.gsub(/(?<!\w)::/, "")
|
|
533
|
+
end
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
class Skyward::API::Assembly::Builder
|
|
4
|
+
Mount = Data.define(
|
|
5
|
+
:api, #: Skyward::API
|
|
6
|
+
:at #: String
|
|
7
|
+
)
|
|
8
|
+
|
|
9
|
+
Use = Data.define(
|
|
10
|
+
:middleware, #: Skyward::API::_Middleware
|
|
11
|
+
:args, #: Array[untyped]
|
|
12
|
+
:kwargs, #: Hash[Symbol, untyped]
|
|
13
|
+
:block #: (^(?) -> untyped)?
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
Static = Data.define(
|
|
17
|
+
:prefix, #: String
|
|
18
|
+
:from #: String
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
# @dynamic mounts
|
|
22
|
+
attr_reader :mounts #: Array[Mount]
|
|
23
|
+
|
|
24
|
+
# @dynamic middleware
|
|
25
|
+
attr_reader :middleware #: Array[Use]
|
|
26
|
+
|
|
27
|
+
# @dynamic statics
|
|
28
|
+
attr_reader :statics #: Array[Static]
|
|
29
|
+
|
|
30
|
+
# @dynamic providers
|
|
31
|
+
attr_reader :providers #: Hash[Symbol, Skyward::API::_Provider & Object]
|
|
32
|
+
|
|
33
|
+
# @rbs return: void
|
|
34
|
+
def initialize
|
|
35
|
+
@mounts = []
|
|
36
|
+
@middleware = []
|
|
37
|
+
@statics = []
|
|
38
|
+
@providers = {}
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# @rbs api: Skyward::API
|
|
42
|
+
# @rbs at: String
|
|
43
|
+
# @rbs return: void
|
|
44
|
+
def mount(api, at: "/")
|
|
45
|
+
# Steep proves a typed caller passes an API, but an untyped one can pass anything.
|
|
46
|
+
unless api.is_a?(Skyward::API) # steep:ignore UnreachableBranch
|
|
47
|
+
raise Skyward::Core::BootError, "mount takes a Skyward::API instance, got #{api.inspect}"
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
@mounts = [*@mounts, Mount.new(api:, at:)]
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# @rbs (Skyward::API::_Middleware middleware, *untyped args, **untyped kwargs) ?{ (?) -> untyped } -> void
|
|
54
|
+
def use(middleware, *args, **kwargs, &block)
|
|
55
|
+
@middleware = [*@middleware, Use.new(middleware:, args:, kwargs:, block:)]
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# @rbs prefix: String
|
|
59
|
+
# @rbs from: String
|
|
60
|
+
# @rbs return: void
|
|
61
|
+
def static(prefix, from:)
|
|
62
|
+
directory = File.expand_path(from)
|
|
63
|
+
unless File.directory?(directory)
|
|
64
|
+
raise Skyward::Core::BootError, "static #{prefix.inspect}: no directory at #{directory}"
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
@statics = [*@statics, Static.new(prefix:, from: directory)]
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
# @rbs (Symbol name, Skyward::API::_Provider & Object provider) -> void
|
|
71
|
+
def provide(name, provider)
|
|
72
|
+
if %i[body request].include?(name)
|
|
73
|
+
raise Skyward::Core::BootError,
|
|
74
|
+
"provide #{name.inspect}: Skyward API fills `#{name}:` itself, so it can't be provided. " \
|
|
75
|
+
"Provide another name."
|
|
76
|
+
end
|
|
77
|
+
if @providers.key?(name)
|
|
78
|
+
raise Skyward::Core::BootError, "provide #{name.inspect}: it's already provided. Provide each name once."
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
@providers = { **@providers, name => provider }
|
|
82
|
+
end
|
|
83
|
+
end
|