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.
Files changed (113) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +185 -47
  3. data/lib/skyward/api/assembly/application.rb +26 -0
  4. data/lib/skyward/api/assembly/boot.rb +533 -0
  5. data/lib/skyward/api/assembly/builder.rb +83 -0
  6. data/lib/skyward/api/assembly/dispatcher.rb +121 -0
  7. data/lib/skyward/api/assembly/static.rb +115 -0
  8. data/lib/skyward/api/assembly.rb +4 -0
  9. data/lib/skyward/api/cli/app_file.rb +38 -0
  10. data/lib/skyward/api/cli/check.rb +145 -0
  11. data/lib/skyward/api/cli/executable.rb +15 -0
  12. data/lib/skyward/api/cli/routes.rb +30 -0
  13. data/lib/skyward/api/cli/serve/reloader.rb +77 -0
  14. data/lib/skyward/api/cli/serve.rb +137 -0
  15. data/lib/skyward/api/cli/serve.ru +16 -0
  16. data/lib/skyward/api/cli.rb +4 -0
  17. data/lib/skyward/api/commands.rb +38 -0
  18. data/lib/skyward/api/endpoints/declarations.rb +124 -0
  19. data/lib/skyward/api/endpoints/helpers.rb +49 -0
  20. data/lib/skyward/api/endpoints/route.rb +13 -0
  21. data/lib/skyward/api/endpoints.rb +4 -0
  22. data/lib/skyward/api/inputs/coercer.rb +425 -0
  23. data/lib/skyward/api/inputs.rb +164 -0
  24. data/lib/skyward/api/middleware/line_logger.rb +20 -0
  25. data/lib/skyward/api/middleware/request_id.rb +26 -0
  26. data/lib/skyward/api/middleware/request_log.rb +46 -0
  27. data/lib/skyward/api/middleware/rescue.rb +81 -0
  28. data/lib/skyward/api/middleware.rb +4 -0
  29. data/lib/skyward/api/openapi/docs.rb +39 -0
  30. data/lib/skyward/api/openapi.rb +393 -0
  31. data/lib/skyward/api/request.rb +127 -0
  32. data/lib/skyward/api/responses/bad_request.rb +18 -0
  33. data/lib/skyward/api/responses/conflict.rb +18 -0
  34. data/lib/skyward/api/responses/created.rb +19 -0
  35. data/lib/skyward/api/responses/forbidden.rb +18 -0
  36. data/lib/skyward/api/responses/no_content.rb +13 -0
  37. data/lib/skyward/api/responses/not_found.rb +18 -0
  38. data/lib/skyward/api/responses/redirect.rb +25 -0
  39. data/lib/skyward/api/responses/unauthorized.rb +18 -0
  40. data/lib/skyward/api/responses/unprocessable.rb +18 -0
  41. data/lib/skyward/api/responses.rb +4 -0
  42. data/lib/skyward/api/return_type_error.rb +4 -0
  43. data/lib/skyward/api/routing/percent_encoding.rb +15 -0
  44. data/lib/skyward/api/routing/router.rb +115 -0
  45. data/lib/skyward/api/routing.rb +4 -0
  46. data/lib/skyward/api/serializer/writers.rb +230 -0
  47. data/lib/skyward/api/serializer.rb +139 -0
  48. data/lib/skyward/api/test/client.rb +160 -0
  49. data/lib/skyward/api/test.rb +8 -0
  50. data/lib/skyward/api/version.rb +5 -1
  51. data/lib/skyward/api.rb +118 -1
  52. data/sig/generated/skyward/api/assembly/application.rbs +22 -0
  53. data/sig/generated/skyward/api/assembly/boot.rbs +217 -0
  54. data/sig/generated/skyward/api/assembly/builder.rbs +77 -0
  55. data/sig/generated/skyward/api/assembly/dispatcher.rbs +84 -0
  56. data/sig/generated/skyward/api/assembly/static.rbs +47 -0
  57. data/sig/generated/skyward/api/assembly.rbs +4 -0
  58. data/sig/generated/skyward/api/cli/app_file.rbs +15 -0
  59. data/sig/generated/skyward/api/cli/check.rbs +76 -0
  60. data/sig/generated/skyward/api/cli/executable.rbs +11 -0
  61. data/sig/generated/skyward/api/cli/routes.rbs +19 -0
  62. data/sig/generated/skyward/api/cli/serve/reloader.rbs +46 -0
  63. data/sig/generated/skyward/api/cli/serve.rbs +56 -0
  64. data/sig/generated/skyward/api/cli.rbs +4 -0
  65. data/sig/generated/skyward/api/commands.rbs +2 -0
  66. data/sig/generated/skyward/api/endpoints/declarations.rbs +81 -0
  67. data/sig/generated/skyward/api/endpoints/helpers.rbs +49 -0
  68. data/sig/generated/skyward/api/endpoints/route.rbs +24 -0
  69. data/sig/generated/skyward/api/endpoints.rbs +4 -0
  70. data/sig/generated/skyward/api/inputs/coercer.rbs +231 -0
  71. data/sig/generated/skyward/api/inputs.rbs +75 -0
  72. data/sig/generated/skyward/api/middleware/line_logger.rbs +13 -0
  73. data/sig/generated/skyward/api/middleware/request_id.rbs +17 -0
  74. data/sig/generated/skyward/api/middleware/request_log.rbs +18 -0
  75. data/sig/generated/skyward/api/middleware/rescue.rbs +41 -0
  76. data/sig/generated/skyward/api/middleware.rbs +4 -0
  77. data/sig/generated/skyward/api/openapi/docs.rbs +17 -0
  78. data/sig/generated/skyward/api/openapi.rbs +198 -0
  79. data/sig/generated/skyward/api/request.rbs +65 -0
  80. data/sig/generated/skyward/api/responses/bad_request.rbs +14 -0
  81. data/sig/generated/skyward/api/responses/conflict.rbs +14 -0
  82. data/sig/generated/skyward/api/responses/created.rbs +15 -0
  83. data/sig/generated/skyward/api/responses/forbidden.rbs +14 -0
  84. data/sig/generated/skyward/api/responses/no_content.rbs +10 -0
  85. data/sig/generated/skyward/api/responses/not_found.rbs +14 -0
  86. data/sig/generated/skyward/api/responses/redirect.rbs +20 -0
  87. data/sig/generated/skyward/api/responses/unauthorized.rbs +14 -0
  88. data/sig/generated/skyward/api/responses/unprocessable.rbs +14 -0
  89. data/sig/generated/skyward/api/responses.rbs +4 -0
  90. data/sig/generated/skyward/api/return_type_error.rbs +4 -0
  91. data/sig/generated/skyward/api/routing/percent_encoding.rbs +11 -0
  92. data/sig/generated/skyward/api/routing/router.rbs +158 -0
  93. data/sig/generated/skyward/api/routing.rbs +4 -0
  94. data/sig/generated/skyward/api/serializer/writers.rbs +126 -0
  95. data/sig/generated/skyward/api/serializer.rbs +79 -0
  96. data/sig/generated/skyward/api/test/client.rbs +117 -0
  97. data/sig/generated/skyward/api/test.rbs +6 -0
  98. data/sig/generated/skyward/api.rbs +38 -0
  99. data/sig/manual/skyward/api/assembly/boot.rbs +3 -0
  100. data/sig/manual/skyward/api/cli/app_file.rbs +3 -0
  101. data/sig/manual/skyward/api/cli/check.rbs +3 -0
  102. data/sig/manual/skyward/api/cli/executable.rbs +3 -0
  103. data/sig/manual/skyward/api/cli/routes.rbs +3 -0
  104. data/sig/manual/skyward/api/cli/serve.rbs +3 -0
  105. data/sig/manual/skyward/api/inputs/coercer.rbs +3 -0
  106. data/sig/manual/skyward/api/openapi/docs.rbs +3 -0
  107. data/sig/manual/skyward/api/openapi.rbs +3 -0
  108. data/sig/manual/skyward/api/routing/percent_encoding.rbs +3 -0
  109. data/sig/manual/skyward/api/serializer/writers.rbs +3 -0
  110. data/sig/manual/skyward/api/test.rbs +3 -0
  111. data/sig/manual/skyward/api.rbs +21 -0
  112. data/sig/manual/zeitwerk/loader.rbs +6 -0
  113. 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