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,393 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ module Skyward::API::OpenAPI
6
+ extend self
7
+
8
+ # @rbs!
9
+ # type schema = Hash[Symbol, untyped]
10
+ # type form = :request | :response
11
+
12
+ Answer = Data.define(
13
+ :status, #: String
14
+ :media_type, #: String?
15
+ :schema #: schema?
16
+ )
17
+
18
+ PATH = "/openapi.json" #: String
19
+
20
+ SERVED = {
21
+ PATH => "the OpenAPI document",
22
+ Docs::PATH => "the API reference"
23
+ }.freeze #: Hash[String, String]
24
+
25
+ # OpenAPI's pattern for the name of a component.
26
+ NAME = /\A[A-Za-z0-9._-]+\z/ #: Regexp
27
+
28
+ JSON_TYPE = "application/json" #: String
29
+
30
+ PROBLEM_TYPE = "application/problem+json" #: String
31
+
32
+ SCALARS = {
33
+ integer: { type: "integer" },
34
+ float: { type: "number" },
35
+ string: { type: "string" },
36
+ bool: { type: "boolean" },
37
+ date: { type: "string", format: "date" },
38
+ time: { type: "string", format: "date-time" },
39
+ untyped: {} #: schema
40
+ }.freeze #: Hash[Skyward::Core::Types::scalar, schema]
41
+
42
+ NULL = { type: "null" }.freeze #: schema
43
+
44
+ PROBLEM = { "$ref": "#/components/schemas/Problem" }.freeze #: schema
45
+
46
+ PROBLEM_SCHEMA = {
47
+ type: "object",
48
+ properties: {
49
+ type: { type: "string" },
50
+ title: { type: "string" },
51
+ status: { type: "integer" },
52
+ detail: { type: "string" },
53
+ errors: {
54
+ type: "array",
55
+ items: {
56
+ type: "object",
57
+ properties: { at: { type: "string" }, message: { type: "string" } },
58
+ required: %w[at message]
59
+ }
60
+ }
61
+ },
62
+ required: %w[type title status]
63
+ }.freeze #: schema
64
+
65
+ NO_CONTENT = Answer.new(status: "204", media_type: nil, schema: nil) #: Answer
66
+
67
+ # A redirect's status is chosen when it's made, so it's documented as the range.
68
+ REDIRECT = Answer.new(status: "3XX", media_type: nil, schema: nil) #: Answer
69
+
70
+ RACK = Answer.new(status: "default", media_type: nil, schema: nil) #: Answer
71
+
72
+ INVALID = Answer.new(status: "422", media_type: PROBLEM_TYPE, schema: PROBLEM) #: Answer
73
+
74
+ REFUSED = [
75
+ Answer.new(status: "413", media_type: PROBLEM_TYPE, schema: PROBLEM),
76
+ Answer.new(status: "415", media_type: PROBLEM_TYPE, schema: PROBLEM)
77
+ ].freeze #: Array[Answer]
78
+
79
+ LOCATION = { location: { schema: { type: "string" } } }.freeze #: Hash[Symbol, untyped]
80
+
81
+ DESCRIPTIONS = {
82
+ "200" => "OK",
83
+ "201" => "Created",
84
+ "204" => "No Content",
85
+ "3XX" => "Redirect",
86
+ **Skyward::API::Serializer::PROBLEMS.values.to_h { |problem| [problem.status.to_s, problem.title] },
87
+ **Skyward::API::Assembly::Dispatcher::INPUT_TITLES.transform_keys(&:to_s),
88
+ "default" => "A Rack response, whose status and content are known only when it's sent"
89
+ }.freeze #: Hash[String, String]
90
+
91
+ # Takes the document unbuilt, so a route or static file at /openapi.json or /docs is refused first.
92
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
93
+ # @rbs static: Skyward::API::Assembly::Static
94
+ # @rbs document: ^() -> schema
95
+ # @rbs return: String
96
+ def json(endpoints, static:, document:)
97
+ served = served(endpoints, static)
98
+ raise Skyward::Core::BootError, served if served
99
+
100
+ JSON.generate(document.call)
101
+ end
102
+
103
+ # Only serving the documents needs /openapi.json and /docs free, so this doesn't check them.
104
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
105
+ # @rbs title: String
106
+ # @rbs version: String
107
+ # @rbs description: String?
108
+ # @rbs schema_names: Hash[Class, String]
109
+ # @rbs return: schema
110
+ def document(endpoints, title:, version:, description:, schema_names:)
111
+ types = endpoints.flat_map { |endpoint| types(endpoint).flat_map { |type| named(type) } }.uniq
112
+ names = operation_ids(endpoints) || names(types, schema_names)
113
+ case names
114
+ when String then raise Skyward::Core::BootError, names
115
+ else assembled(endpoints, types, { title:, version:, description: }.compact, names)
116
+ end
117
+ end
118
+
119
+ private
120
+
121
+ # The request: keyword is Skyward's, not part of the HTTP contract.
122
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
123
+ # @rbs return: Array[Skyward::API::Routing::Router::Keyword]
124
+ def described(endpoint) = endpoint.keywords.reject { |keyword| keyword.source == :request }
125
+
126
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
127
+ # @rbs return: Array[Skyward::Core::Types::t]
128
+ def types(endpoint)
129
+ returned = endpoint.returns.filter_map do |member|
130
+ case member
131
+ when Skyward::API::Routing::Router::Created then member.type
132
+ when Skyward::API::Routing::Router::Response, Skyward::API::Routing::Router::Rack then nil
133
+ else member
134
+ end
135
+ end
136
+ [*described(endpoint).map(&:type), *returned]
137
+ end
138
+
139
+ # @rbs type: Skyward::Core::Types::t
140
+ # @rbs return: Array[Skyward::Core::Types::Named]
141
+ def named(type)
142
+ case type
143
+ when Skyward::Core::Types::Nullable, Skyward::Core::Types::ArrayOf, Skyward::Core::Types::HashOf
144
+ named(type.type)
145
+ when Skyward::Core::Types::Record then type.fields.flat_map { |field| named(field.type) }
146
+ when Skyward::Core::Types::Named then [type, *type.fields.flat_map { |field| named(field.type) }]
147
+ when Skyward::Core::Types::Union then type.types.flat_map { |member| named(member) }
148
+ else []
149
+ end
150
+ end
151
+
152
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
153
+ # @rbs static: Skyward::API::Assembly::Static
154
+ # @rbs return: String?
155
+ def served(endpoints, static)
156
+ SERVED.lazy.filter_map { |at, serves| taken(at, serves, endpoints, static) }.first
157
+ end
158
+
159
+ # @rbs at: String
160
+ # @rbs serves: String
161
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
162
+ # @rbs static: Skyward::API::Assembly::Static
163
+ # @rbs return: String?
164
+ def taken(at, serves, endpoints, static)
165
+ routed = endpoints.find { |endpoint| path(endpoint.pattern) == at }
166
+ if routed
167
+ return "#{routed.label}\n With docs: true, #{at} serves #{serves}. Change the route's path, or leave out docs:."
168
+ end
169
+
170
+ file = static.file(at)
171
+ return unless file
172
+
173
+ "static serves #{file} at #{at}, where docs: true serves #{serves}. Move the file, or leave out docs:."
174
+ end
175
+
176
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
177
+ # @rbs return: String?
178
+ def operation_ids(endpoints)
179
+ id, same = endpoints.group_by { |endpoint| operation_id(endpoint) }.find { |_, shared| shared.size > 1 }
180
+ return unless same
181
+
182
+ first = same.fetch(0)
183
+ second = same.fetch(1)
184
+ "#{second.label}\n Its OpenAPI operation ID, #{id}, is #{first.label}'s too, " \
185
+ "but each operation needs its own. With docs: true, route each method once, and mount each class once."
186
+ end
187
+
188
+ # @rbs types: Array[Skyward::Core::Types::Named]
189
+ # @rbs schema_names: Hash[Class, String]
190
+ # @rbs return: Hash[Class, String] | String
191
+ def names(types, schema_names)
192
+ chosen = types.to_h { |type| [type.klass, schema_names.fetch(type.klass) { dotted(type.name) }] }
193
+ invalid, name = chosen.find { |_, named| !NAME.match?(named) }
194
+ if invalid
195
+ return "#{invalid}'s schema name, #{name.inspect}, isn't one OpenAPI allows: use only letters, digits, " \
196
+ "., - and _. Name it with Skyward.app(schema_names:)."
197
+ end
198
+
199
+ taken = [["Problem", "Skyward API's problem+json"], *chosen.map { |klass, named| [named, klass.to_s] }]
200
+ same = taken.group_by(&:first).values.find { |shared| shared.size > 1 }
201
+ return chosen unless same
202
+
203
+ (name, first), (_, second) = same.fetch(0), same.fetch(1)
204
+ "#{first} and #{second} both have the schema name #{name}, but each schema needs its own. " \
205
+ "Name one of them with Skyward.app(schema_names:)."
206
+ end
207
+
208
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
209
+ # @rbs types: Array[Skyward::Core::Types::Named]
210
+ # @rbs info: Hash[Symbol, String]
211
+ # @rbs names: Hash[Class, String]
212
+ # @rbs return: schema
213
+ def assembled(endpoints, types, info, names)
214
+ {
215
+ openapi: "3.1.0",
216
+ info:,
217
+ tags: endpoints.uniq { |endpoint| endpoint.api.class }.map do |endpoint|
218
+ { name: tag(endpoint), description: endpoint.api.class.class_description }.compact
219
+ end,
220
+ paths: endpoints.group_by { |endpoint| path(endpoint.pattern) }.transform_values do |routed|
221
+ routed.to_h { |endpoint| [endpoint.verb.downcase, operation(endpoint, names)] }
222
+ end,
223
+ components: { schemas: components(endpoints, types, names) }
224
+ }
225
+ end
226
+
227
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
228
+ # @rbs names: Hash[Class, String]
229
+ # @rbs return: schema
230
+ def operation(endpoint, names)
231
+ bodies, others = described(endpoint).partition { |keyword| keyword.source == :body }
232
+ body = bodies.first
233
+ parameters = others.map { |keyword| parameter(keyword, names) }
234
+ {
235
+ tags: [tag(endpoint)],
236
+ summary: endpoint.summary,
237
+ description: endpoint.description,
238
+ operationId: operation_id(endpoint),
239
+ parameters: (parameters unless parameters.empty?),
240
+ requestBody: (request_body(body, names) if body),
241
+ responses: responses(endpoint, body, names)
242
+ }.compact
243
+ end
244
+
245
+ # A path or query value can't be null, so its schema leaves null out, and it's
246
+ # always a String, so an untyped one is a string.
247
+ # @rbs keyword: Skyward::API::Routing::Router::Keyword
248
+ # @rbs names: Hash[Class, String]
249
+ # @rbs return: schema
250
+ def parameter(keyword, names)
251
+ type = keyword.type
252
+ carried = type.is_a?(Skyward::Core::Types::Nullable) ? type.type : type
253
+ {
254
+ name: keyword.name,
255
+ in: keyword.source,
256
+ required: keyword.source == :path || required?(keyword.required, type, :request),
257
+ schema: carried == Skyward::API::Serializer::UNTYPED ? SCALARS.fetch(:string) : schema(carried, :request, names)
258
+ }
259
+ end
260
+
261
+ # @rbs keyword: Skyward::API::Routing::Router::Keyword
262
+ # @rbs names: Hash[Class, String]
263
+ # @rbs return: schema
264
+ def request_body(keyword, names)
265
+ {
266
+ required: required?(keyword.required, keyword.type, :request),
267
+ content: { JSON_TYPE => { schema: schema(keyword.type, :request, names) } }
268
+ }
269
+ end
270
+
271
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
272
+ # @rbs body: Skyward::API::Routing::Router::Keyword?
273
+ # @rbs names: Hash[Class, String]
274
+ # @rbs return: Hash[String, schema]
275
+ def responses(endpoint, body, names)
276
+ answers = [
277
+ *[*endpoint.returns, *endpoint.providers.flat_map(&:responses)].map { |member| answer(member, names) },
278
+ *([INVALID] unless described(endpoint).empty?),
279
+ *(REFUSED if body)
280
+ ] #: Array[Answer]
281
+ answers.group_by(&:status).sort_by(&:first).to_h { |status, same| [status, response(status, same)] }
282
+ end
283
+
284
+ # @rbs member: Skyward::API::Routing::Router::returned
285
+ # @rbs names: Hash[Class, String]
286
+ # @rbs return: Answer
287
+ def answer(member, names)
288
+ case member
289
+ when Skyward::API::Routing::Router::Created
290
+ Answer.new(status: "201", media_type: JSON_TYPE, schema: schema(member.type, :response, names))
291
+ when Skyward::API::Routing::Router::Response then response_value(member.klass)
292
+ when Skyward::API::Routing::Router::Rack then RACK
293
+ else Answer.new(status: "200", media_type: JSON_TYPE, schema: schema(member, :response, names))
294
+ end
295
+ end
296
+
297
+ # @rbs klass: Class
298
+ # @rbs return: Answer
299
+ def response_value(klass)
300
+ problem = Skyward::API::Serializer::PROBLEMS.fetch(klass, nil)
301
+ if problem then Answer.new(status: problem.status.to_s, media_type: PROBLEM_TYPE, schema: PROBLEM)
302
+ elsif klass == Skyward::API::Responses::Redirect then REDIRECT
303
+ else NO_CONTENT
304
+ end
305
+ end
306
+
307
+ # Every answer with one status has the same media type, because the status says what's sent.
308
+ # @rbs status: String
309
+ # @rbs answers: Array[Answer]
310
+ # @rbs return: schema
311
+ def response(status, answers)
312
+ base = { description: DESCRIPTIONS.fetch(status) }
313
+ media_type = answers.fetch(0).media_type
314
+ schemas = answers.filter_map(&:schema).uniq
315
+ if media_type
316
+ { **base, content: { media_type => { schema: schemas.one? ? schemas.fetch(0) : { oneOf: schemas } } } }
317
+ elsif status == REDIRECT.status then { **base, headers: LOCATION }
318
+ else
319
+ base
320
+ end
321
+ end
322
+
323
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
324
+ # @rbs types: Array[Skyward::Core::Types::Named]
325
+ # @rbs names: Hash[Class, String]
326
+ # @rbs return: Hash[String, schema]
327
+ def components(endpoints, types, names)
328
+ requested = endpoints.flat_map { |endpoint| described(endpoint).flat_map { |keyword| named(keyword.type) } }
329
+ types.to_h do |type|
330
+ [names.fetch(type.klass), object(type.fields, requested.include?(type) ? :request : :response, names)]
331
+ end.merge("Problem" => PROBLEM_SCHEMA).sort_by(&:first).to_h
332
+ end
333
+
334
+ # @rbs type: Skyward::Core::Types::t
335
+ # @rbs form: form
336
+ # @rbs names: Hash[Class, String]
337
+ # @rbs return: schema
338
+ def schema(type, form, names)
339
+ case type
340
+ when Skyward::Core::Types::Scalar then SCALARS.fetch(type.name)
341
+ when Skyward::Core::Types::Literal then type.value.nil? ? NULL : { const: type.value }
342
+ when Skyward::Core::Types::Enum then { type: "string", enum: type.symbols.map(&:name) }
343
+ when Skyward::Core::Types::Nullable then nullable(schema(type.type, form, names))
344
+ when Skyward::Core::Types::ArrayOf then { type: "array", items: schema(type.type, form, names) }
345
+ when Skyward::Core::Types::HashOf then { type: "object", additionalProperties: schema(type.type, form, names) }
346
+ when Skyward::Core::Types::Record then object(type.fields, form, names)
347
+ when Skyward::Core::Types::Named then { "$ref": "#/components/schemas/#{names.fetch(type.klass)}" }
348
+ else { oneOf: type.types.map { |member| schema(member, form, names) } }
349
+ end
350
+ end
351
+
352
+ # @rbs schema: schema
353
+ # @rbs return: schema
354
+ def nullable(schema)
355
+ type = schema[:type]
356
+ type.is_a?(String) && !schema.key?(:enum) ? schema.merge(type: [type, "null"]) : { anyOf: [schema, NULL] }
357
+ end
358
+
359
+ # @rbs fields: Array[Skyward::Core::Types::Field]
360
+ # @rbs form: form
361
+ # @rbs names: Hash[Class, String]
362
+ # @rbs return: schema
363
+ def object(fields, form, names)
364
+ {
365
+ type: "object",
366
+ properties: fields.to_h { |field| [field.name, schema(field.type, form, names)] },
367
+ required: fields.filter_map { |field| field.name if required?(field.required, field.type, form) }
368
+ }
369
+ end
370
+
371
+ # A request may leave out a nullable value, which arrives as nil, but a response always writes it.
372
+ # @rbs required: bool
373
+ # @rbs type: Skyward::Core::Types::t
374
+ # @rbs form: form
375
+ # @rbs return: bool
376
+ def required?(required, type, form) = required && (form == :response || !type.is_a?(Skyward::Core::Types::Nullable))
377
+
378
+ # @rbs pattern: Array[String | Symbol]
379
+ # @rbs return: String
380
+ def path(pattern) = pattern.map { |part| part.is_a?(Symbol) ? "{#{part}}" : part }.join("/")
381
+
382
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
383
+ # @rbs return: String
384
+ def tag(endpoint) = dotted(endpoint.api.class.name)
385
+
386
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
387
+ # @rbs return: String
388
+ def operation_id(endpoint) = "#{tag(endpoint)}_#{endpoint.to}"
389
+
390
+ # @rbs name: String
391
+ # @rbs return: String
392
+ def dotted(name) = name.gsub("::", ".")
393
+ end
@@ -0,0 +1,127 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Request
4
+ # Rack passes these two headers without the HTTP_ prefix the others get.
5
+ UNPREFIXED = { "CONTENT_TYPE" => "content-type", "CONTENT_LENGTH" => "content-length" }.freeze #: Hash[String, String]
6
+
7
+ OCTET = "(?:25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])" #: String
8
+
9
+ # Rack's trusted proxies: loopback, the private ranges and Unix sockets.
10
+ TRUSTED_PROXY = Regexp.union(
11
+ /\A127(?:\.#{OCTET}){3}\z/,
12
+ /\A::1\z/,
13
+ /\Af[cd][0-9a-f]{2}(?::[0-9a-f]{0,4}){0,7}\z/i,
14
+ /\A10(?:\.#{OCTET}){3}\z/,
15
+ /\A172\.(?:1[6-9]|2[0-9]|3[01])(?:\.#{OCTET}){2}\z/,
16
+ /\A192\.168(?:\.#{OCTET}){2}\z/,
17
+ /\Alocalhost\z|\Aunix(?:\z|:)/i
18
+ ) #: Regexp
19
+
20
+ IPV6 = Regexp.union(
21
+ /(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}/,
22
+ /(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?::(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?/,
23
+ /(?:[0-9A-Fa-f]{1,4}:){6}\d+\.\d+\.\d+\.\d+/,
24
+ /(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?::(?:[0-9A-Fa-f]{1,4}:)*\d+\.\d+\.\d+\.\d+/,
25
+ /[Ff][Ee]80(?::[0-9A-Fa-f]{1,4}){7}%[-0-9A-Za-z._~]+/,
26
+ /
27
+ [Ff][Ee]80:
28
+ (?:
29
+ (?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?::(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?
30
+ |
31
+ :(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?
32
+ )?
33
+ :[0-9A-Fa-f]{1,4}%[-0-9A-Za-z._~]+
34
+ /x
35
+ ) #: Regexp
36
+
37
+ # Rack's authority grammar: a bracketed IPv6 address or an RFC 3986 host, then an optional port.
38
+ AUTHORITY = /
39
+ \A
40
+ (?:
41
+ \[(?<address>#{IPV6})\]
42
+ |
43
+ (?<address>[-a-zA-Z0-9._~%!$&'()*+,;=]*?)
44
+ )
45
+ (?::\d+)?
46
+ \z
47
+ /x #: Regexp
48
+
49
+ # @dynamic env
50
+ attr_reader :env #: Hash[String, untyped]
51
+
52
+ # @dynamic headers
53
+ attr_reader :headers #: Hash[String, String]
54
+
55
+ # @dynamic cookies
56
+ attr_reader :cookies #: Hash[String, String]
57
+
58
+ # @dynamic ip
59
+ attr_reader :ip #: String?
60
+
61
+ # @dynamic request_id
62
+ attr_reader :request_id #: String
63
+
64
+ # @rbs env: Hash[String, untyped]
65
+ # @rbs return: void
66
+ def initialize(env)
67
+ @env = env
68
+ @headers = read_headers(env)
69
+ @cookies = read_cookies(env["HTTP_COOKIE"])
70
+ @ip = client_ip(addresses(env["REMOTE_ADDR"]), addresses(env["HTTP_X_FORWARDED_FOR"]).map { |entry| bare(entry) })
71
+ @request_id = env.fetch("skyward.request_id")
72
+ freeze
73
+ end
74
+
75
+ private
76
+
77
+ # @rbs env: Hash[String, untyped]
78
+ # @rbs return: Hash[String, String]
79
+ def read_headers(env)
80
+ env.filter_map do |key, value|
81
+ name = UNPREFIXED[key] || (key.delete_prefix("HTTP_").downcase.tr("_", "-") if key.start_with?("HTTP_"))
82
+ [name, value] if name
83
+ end.to_h.freeze
84
+ end
85
+
86
+ # @rbs header: String?
87
+ # @rbs return: Hash[String, String]
88
+ def read_cookies(header)
89
+ # Split as bytes, because String#split raises on a String that isn't valid
90
+ # UTF-8, and a client can send one.
91
+ pairs = header.to_s.b.split(/; */).reject(&:empty?).map do |cookie|
92
+ name, value = cookie.split("=", 2)
93
+ [String.new(name.to_s, encoding: Encoding::UTF_8), Skyward::API::Routing::PercentEncoding.decode(value.to_s)]
94
+ end
95
+ # The first of two cookies with one name wins, as in Rack.
96
+ pairs.uniq(&:first).to_h.freeze
97
+ end
98
+
99
+ # @rbs header: String?
100
+ # @rbs return: Array[String]
101
+ def addresses(header) = header.to_s.b.split(/[,\s]+/).reject(&:empty?)
102
+
103
+ # Rack wraps a bare IPv6 address, which clients send without brackets.
104
+ # @rbs entry: String
105
+ # @rbs return: String?
106
+ def bare(entry)
107
+ wrapped = !entry.start_with?("[") && entry.count(":") > 1 ? "[#{entry}]" : entry
108
+ wrapped[AUTHORITY, :address]
109
+ end
110
+
111
+ # As Rack does, a forwarded address is trusted only from a trusted proxy,
112
+ # and the client is the last address that isn't one.
113
+ # @rbs remote: Array[String?]
114
+ # @rbs forwarded: Array[String?]
115
+ # @rbs return: String?
116
+ def client_ip(remote, forwarded)
117
+ (untrusted(remote) || untrusted(forwarded) || [forwarded.first || remote.first]).first
118
+ end
119
+
120
+ # @rbs addresses: Array[String?]
121
+ # @rbs return: Array[String?]?
122
+ def untrusted(addresses)
123
+ # An entry that isn't an address is nil, which is never trusted.
124
+ index = addresses.rindex { |address| address.nil? || !TRUSTED_PROXY.match?(address) }
125
+ [addresses.fetch(index)] if index
126
+ end
127
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::BadRequest
4
+ # @dynamic detail
5
+ attr_reader :detail #: String
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::Conflict
4
+ # @dynamic detail
5
+ attr_reader :detail #: String
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ # @rbs generic out T
4
+ class Skyward::API::Responses::Created
5
+ # @dynamic value
6
+ attr_reader :value #: T
7
+
8
+ # @dynamic headers
9
+ attr_reader :headers #: Hash[String, String]
10
+
11
+ # @rbs value: T
12
+ # @rbs headers: Hash[String, String]
13
+ # @rbs return: void
14
+ def initialize(value:, headers:)
15
+ @value = value
16
+ @headers = headers
17
+ freeze
18
+ end
19
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::Forbidden
4
+ # @dynamic detail
5
+ attr_reader :detail #: String
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::NoContent
4
+ # @dynamic headers
5
+ attr_reader :headers #: Hash[String, String]
6
+
7
+ # @rbs headers: Hash[String, String]
8
+ # @rbs return: void
9
+ def initialize(headers:)
10
+ @headers = headers
11
+ freeze
12
+ end
13
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::NotFound
4
+ # @dynamic detail
5
+ attr_reader :detail #: String?
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String?
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end
@@ -0,0 +1,25 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::Redirect
4
+ STATUSES = [301, 302, 303, 307, 308].freeze #: Array[Integer]
5
+
6
+ # @dynamic to
7
+ attr_reader :to #: String
8
+
9
+ # @dynamic status
10
+ attr_reader :status #: Integer
11
+
12
+ # @dynamic headers
13
+ attr_reader :headers #: Hash[String, String]
14
+
15
+ # @rbs to: String
16
+ # @rbs status: Integer
17
+ # @rbs headers: Hash[String, String]
18
+ # @rbs return: void
19
+ def initialize(to:, status:, headers:)
20
+ @to = to
21
+ @status = status
22
+ @headers = headers
23
+ freeze
24
+ end
25
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::Unauthorized
4
+ # @dynamic detail
5
+ attr_reader :detail #: String
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Responses::Unprocessable
4
+ # @dynamic detail
5
+ attr_reader :detail #: String
6
+
7
+ # @dynamic headers
8
+ attr_reader :headers #: Hash[String, String]
9
+
10
+ # @rbs detail: String
11
+ # @rbs headers: Hash[String, String]
12
+ # @rbs return: void
13
+ def initialize(detail:, headers:)
14
+ @detail = detail
15
+ @headers = headers
16
+ freeze
17
+ end
18
+ end