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,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
|