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,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Responses
4
+ end
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::ReturnTypeError < StandardError
4
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Routing::PercentEncoding
4
+ extend self
5
+
6
+ ESCAPE = /%\h\h/ #: Regexp
7
+
8
+ # Lenient, unlike URI.decode_uri_component, because servers pass the path
9
+ # through undecoded and a malformed escape is the client's to send.
10
+ # @rbs text: String
11
+ # @rbs return: String
12
+ def decode(text)
13
+ text.b.gsub(ESCAPE) { |escape| escape.delete_prefix("%").hex.chr }.force_encoding(Encoding::UTF_8)
14
+ end
15
+ end
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Routing::Router
4
+ # @rbs! type returned = Skyward::Core::Types::t | Created | Response | Rack
5
+
6
+ Keyword = Data.define(
7
+ :name, #: Symbol
8
+ :source, #: :path | :query | :body | :request
9
+ :required, #: bool
10
+ :type #: Skyward::Core::Types::t
11
+ )
12
+
13
+ # Skyward::API::Responses::Created[T], which the reader can't read, so its value's type is read on its own.
14
+ Created = Data.define(
15
+ :type #: Skyward::Core::Types::t
16
+ )
17
+
18
+ Response = Data.define(
19
+ :klass #: Class
20
+ )
21
+
22
+ Rack = Data.define
23
+
24
+ # A provider without a signature has no value to check, so its value is nil.
25
+ Provider = Data.define(
26
+ :name, #: Symbol
27
+ :callable, #: Skyward::API::_Provider
28
+ :value, #: Array[RBS::Types::t]?
29
+ :responses, #: Array[Response]
30
+ :serializer #: Skyward::API::Serializer
31
+ )
32
+
33
+ Endpoint = Data.define(
34
+ :verb, #: String
35
+ :pattern, #: Array[String | Symbol]
36
+ :api, #: Skyward::API
37
+ :to, #: Symbol
38
+ :label, #: String
39
+ :summary, #: String?
40
+ :description, #: String?
41
+ :keywords, #: Array[Keyword]
42
+ :providers, #: Array[Provider]
43
+ :returns, #: Array[returned]
44
+ :signature, #: String
45
+ :inputs, #: Skyward::API::Inputs
46
+ :serializer #: Skyward::API::Serializer
47
+ )
48
+
49
+ Match = Data.define(
50
+ :api, #: Skyward::API
51
+ :to, #: Symbol
52
+ :inputs, #: Skyward::API::Inputs
53
+ :params, #: Hash[Symbol, String]
54
+ :serializer #: Skyward::API::Serializer
55
+ )
56
+
57
+ METHODS = %w[GET HEAD POST PUT PATCH DELETE OPTIONS].freeze #: Array[String]
58
+
59
+ # @rbs @endpoints: Array[Endpoint]
60
+
61
+ # @rbs endpoints: Array[Endpoint]
62
+ # @rbs return: void
63
+ def initialize(endpoints)
64
+ @endpoints = endpoints
65
+ end
66
+
67
+ # @rbs verb: String
68
+ # @rbs path: String
69
+ # @rbs return: Match?
70
+ def match(verb, path)
71
+ segments = path.split("/", -1)
72
+ routed = verb == "HEAD" ? "GET" : verb
73
+ @endpoints.lazy.filter_map { |endpoint| match_endpoint(endpoint, routed, segments) }.first
74
+ end
75
+
76
+ # @rbs path: String
77
+ # @rbs return: Array[String]
78
+ def allowed(path)
79
+ segments = path.split("/", -1)
80
+ verbs = @endpoints.filter_map { |endpoint| endpoint.verb if params_for(endpoint.pattern, segments) }
81
+ return [] if verbs.empty?
82
+
83
+ implied = verbs.include?("GET") ? %w[HEAD OPTIONS] : %w[OPTIONS]
84
+ METHODS & (verbs + implied)
85
+ end
86
+
87
+ private
88
+
89
+ # @rbs endpoint: Endpoint
90
+ # @rbs verb: String
91
+ # @rbs segments: Array[String]
92
+ # @rbs return: Match?
93
+ def match_endpoint(endpoint, verb, segments)
94
+ return unless endpoint.verb == verb
95
+
96
+ params = params_for(endpoint.pattern, segments)
97
+ return unless params
98
+
99
+ Match.new(api: endpoint.api, to: endpoint.to, inputs: endpoint.inputs, params:, serializer: endpoint.serializer)
100
+ end
101
+
102
+ # @rbs pattern: Array[String | Symbol]
103
+ # @rbs segments: Array[String]
104
+ # @rbs return: Hash[Symbol, String]?
105
+ def params_for(pattern, segments)
106
+ return unless pattern.length == segments.length
107
+
108
+ pairs = segments.zip(pattern)
109
+ return unless pairs.all? { |segment, part| part.is_a?(Symbol) ? !segment.empty? : segment == part }
110
+
111
+ pairs.filter_map do |segment, part|
112
+ [part, Skyward::API::Routing::PercentEncoding.decode(segment)] if part.is_a?(Symbol)
113
+ end.to_h
114
+ end
115
+ end
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Routing
4
+ end
@@ -0,0 +1,230 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ # Time#iso8601 is core only from Ruby 3.4.
5
+ require "time"
6
+
7
+ module Skyward::API::Serializer::Writers
8
+ extend self
9
+
10
+ Writer = Data.define(
11
+ :name, #: String
12
+ :fits, #: ^(untyped) -> bool
13
+ :write #: ^(untyped, String) -> untyped
14
+ )
15
+
16
+ Misfit = Data.define(
17
+ :at, #: String
18
+ :expected, #: String
19
+ :got #: String
20
+ )
21
+
22
+ # @rbs type: Skyward::Core::Types::t
23
+ # @rbs return: Writer
24
+ def writer(type)
25
+ case type
26
+ when Skyward::Core::Types::Scalar then scalar(type.name)
27
+ when Skyward::Core::Types::Literal then literal(type.value)
28
+ when Skyward::Core::Types::Enum then enum(type.symbols)
29
+ when Skyward::Core::Types::Nullable then nullable(type.type)
30
+ when Skyward::Core::Types::ArrayOf then array(writer(type.type))
31
+ when Skyward::Core::Types::HashOf then hash_of(writer(type.type))
32
+ when Skyward::Core::Types::Record then record(type.fields)
33
+ when Skyward::Core::Types::Named then named(type)
34
+ when Skyward::Core::Types::Union then union(type.types.map { |member| writer(member) })
35
+ end
36
+ end
37
+
38
+ # @rbs members: Array[Writer]
39
+ # @rbs return: Writer
40
+ def union(members)
41
+ name = members.map(&:name).join(" | ")
42
+ Writer.new(
43
+ name:,
44
+ fits: ->(value) { members.any? { |member| member.fits.call(value) } },
45
+ write: lambda do |value, at|
46
+ fitting = members.select { |candidate| candidate.fits.call(value) }
47
+ fitting.empty? ? misfit(name, value, at) : first_written(fitting, value, at)
48
+ end
49
+ )
50
+ end
51
+
52
+ # @rbs name: String
53
+ # @rbs fits: ^(untyped) -> bool
54
+ # @rbs write: ^(untyped, String) -> untyped
55
+ # @rbs return: Writer
56
+ def checked(name, fits, write)
57
+ Writer.new(
58
+ name:,
59
+ fits:,
60
+ write: lambda do |value, at|
61
+ fits.call(value) ? write.call(value, at) : misfit(name, value, at)
62
+ end
63
+ )
64
+ end
65
+
66
+ private
67
+
68
+ # @rbs fitting: Array[Writer]
69
+ # @rbs value: untyped
70
+ # @rbs at: String
71
+ # @rbs failed: Misfit?
72
+ # @rbs return: untyped
73
+ def first_written(fitting, value, at, failed = nil)
74
+ head, *rest = fitting
75
+ return failed unless head
76
+
77
+ written = head.write.call(value, at)
78
+ written.is_a?(Misfit) ? first_written(rest, value, at, failed || written) : written
79
+ end
80
+
81
+ # @rbs name: Skyward::Core::Types::scalar
82
+ # @rbs return: Writer
83
+ def scalar(name)
84
+ case name
85
+ when :integer then checked("Integer", ->(value) { value.is_a?(Integer) }, ->(value, _) { value })
86
+ when :float then checked("Float", ->(value) { value.is_a?(Float) }, ->(value, _) { value })
87
+ when :string then checked("String", ->(value) { value.is_a?(String) }, ->(value, _) { value })
88
+ when :bool then checked("bool", ->(value) { [true, false].include?(value) }, ->(value, _) { value })
89
+ when :date then checked("Date", ->(value) { value.is_a?(Date) }, ->(value, _) { date(value) })
90
+ when :time then checked("Time", ->(value) { value.is_a?(Time) }, ->(value, _) { time(value) })
91
+ when :untyped then Writer.new(name: "untyped", fits: ->(_) { true }, write: ->(value, at) { untyped(value, at) })
92
+ end
93
+ end
94
+
95
+ # @rbs value: Skyward::Core::Types::literal
96
+ # @rbs return: Writer
97
+ def literal(value)
98
+ checked(value.inspect, ->(given) { value.eql?(given) }, ->(given, _) { given })
99
+ end
100
+
101
+ # @rbs symbols: Array[Symbol]
102
+ # @rbs return: Writer
103
+ def enum(symbols)
104
+ checked(symbols.map(&:inspect).join(" | "), ->(value) { symbols.include?(value) }, ->(value, _) { value.name })
105
+ end
106
+
107
+ # @rbs type: Skyward::Core::Types::t
108
+ # @rbs return: Writer
109
+ def nullable(type)
110
+ inner = writer(type)
111
+ grouped = type.is_a?(Skyward::Core::Types::Union) ||
112
+ (type.is_a?(Skyward::Core::Types::Enum) && type.symbols.size > 1)
113
+ Writer.new(
114
+ name: grouped ? "(#{inner.name})?" : "#{inner.name}?",
115
+ fits: ->(value) { value.nil? || inner.fits.call(value) },
116
+ write: ->(value, at) { value.nil? ? nil : inner.write.call(value, at) }
117
+ )
118
+ end
119
+
120
+ # @rbs item: Writer
121
+ # @rbs return: Writer
122
+ def array(item)
123
+ checked(
124
+ "Array[#{item.name}]",
125
+ ->(value) { value.is_a?(Array) },
126
+ ->(value, at) { items(value.each_with_index.map { |entry, index| item.write.call(entry, "#{at}[#{index}]") }) }
127
+ )
128
+ end
129
+
130
+ # @rbs value: Writer
131
+ # @rbs return: Writer
132
+ def hash_of(value)
133
+ checked(
134
+ "Hash[String, #{value.name}]",
135
+ ->(given) { given.is_a?(Hash) && given.each_key.all? { |key| key.is_a?(String) || key.is_a?(Symbol) } },
136
+ lambda do |given, at|
137
+ object(given.map { |key, entry| [key.to_s, value.write.call(entry, "#{at}[#{JSON.generate(key.to_s)}]")] })
138
+ end
139
+ )
140
+ end
141
+
142
+ # @rbs fields: Array[Skyward::Core::Types::Field]
143
+ # @rbs return: Writer
144
+ def record(fields)
145
+ writers = fields.map { |field| [field, writer(field.type)] } #: Array[[Skyward::Core::Types::Field, Writer]]
146
+ declared = writers.map { |field, writer| "#{"?" unless field.required}#{field.name}: #{writer.name}" }
147
+ checked(
148
+ "{ #{declared.join(", ")} }",
149
+ ->(value) { value.is_a?(Hash) },
150
+ ->(value, at) { object(writers.filter_map { |field, writer| entry(field, writer, value, at) }) }
151
+ )
152
+ end
153
+
154
+ # @rbs field: Skyward::Core::Types::Field
155
+ # @rbs writer: Writer
156
+ # @rbs hash: Hash[untyped, untyped]
157
+ # @rbs at: String
158
+ # @rbs return: [Symbol, untyped]?
159
+ def entry(field, writer, hash, at)
160
+ name = field.name
161
+ if hash.key?(name) then [name, writer.write.call(hash[name], "#{at}.#{name}")]
162
+ elsif field.required then [name, Misfit.new(at: "#{at}.#{name}", expected: writer.name, got: "nothing")]
163
+ end
164
+ end
165
+
166
+ # Only declared readers are called, never to_h, so nothing else the object holds is written.
167
+ # @rbs type: Skyward::Core::Types::Named
168
+ # @rbs return: Writer
169
+ def named(type)
170
+ klass = type.klass
171
+ writers = type.fields.map { |field| [field.name, writer(field.type)] } #: Array[[Symbol, Writer]]
172
+ checked(
173
+ type.name,
174
+ ->(value) { value.is_a?(klass) },
175
+ lambda do |value, at|
176
+ object(writers.map { |name, writer| [name, writer.write.call(value.public_send(name), "#{at}.#{name}")] })
177
+ end
178
+ )
179
+ end
180
+
181
+ # strftime rather than iso8601, which writes a DateTime with its time.
182
+ # @rbs value: Date
183
+ # @rbs return: String
184
+ def date(value) = value.strftime("%Y-%m-%d")
185
+
186
+ # Six fractional digits, so a time read back from JSON equals the one written.
187
+ # @rbs value: Time
188
+ # @rbs return: String
189
+ def time(value) = value.getutc.iso8601(6)
190
+
191
+ # @rbs value: untyped
192
+ # @rbs at: String
193
+ # @rbs return: untyped
194
+ def untyped(value, at)
195
+ case value
196
+ when nil, true, false, Integer, Float, String then value
197
+ when Symbol then value.name
198
+ when Date then date(value)
199
+ when Time then time(value)
200
+ when Hash then object(value.map { |key, item| [key, untyped(item, "#{at}.#{key}")] })
201
+ when Array then items(value.each_with_index.map { |item, index| untyped(item, "#{at}[#{index}]") })
202
+ else value.respond_to?(:to_h) ? untyped(value.to_h, at) : misfit("something with to_h", value, at)
203
+ end
204
+ end
205
+
206
+ # @rbs written: Array[untyped]
207
+ # @rbs return: untyped
208
+ def items(written) = written.find { |item| item.is_a?(Misfit) } || written
209
+
210
+ # @rbs pairs: Array[[untyped, untyped]]
211
+ # @rbs return: untyped
212
+ def object(pairs)
213
+ misfit = pairs.find { |_, written| written.is_a?(Misfit) }
214
+ misfit ? misfit.last : pairs.to_h
215
+ end
216
+
217
+ # Names a value by its class unless it's a scalar, so a message never carries a String or an object's fields.
218
+ # @rbs expected: String
219
+ # @rbs value: untyped
220
+ # @rbs at: String
221
+ # @rbs return: Misfit
222
+ def misfit(expected, value, at)
223
+ got =
224
+ case value
225
+ when nil, true, false, Symbol, Integer, Float then value.inspect
226
+ else value.class.inspect
227
+ end
228
+ Misfit.new(at:, expected:, got:)
229
+ end
230
+ end
@@ -0,0 +1,139 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ class Skyward::API::Serializer
6
+ JSON_TYPE = { "content-type" => "application/json" }.freeze #: Hash[String, String]
7
+
8
+ Problem = Data.define(
9
+ :status, #: Integer
10
+ :title #: String
11
+ )
12
+
13
+ PROBLEMS = {
14
+ Skyward::API::Responses::BadRequest => Problem.new(status: 400, title: "Bad Request"),
15
+ Skyward::API::Responses::Unauthorized => Problem.new(status: 401, title: "Unauthorized"),
16
+ Skyward::API::Responses::Forbidden => Problem.new(status: 403, title: "Forbidden"),
17
+ Skyward::API::Responses::NotFound => Problem.new(status: 404, title: "Not Found"),
18
+ Skyward::API::Responses::Conflict => Problem.new(status: 409, title: "Conflict"),
19
+ Skyward::API::Responses::Unprocessable => Problem.new(status: 422, title: "Unprocessable Content")
20
+ }.freeze #: Hash[Class, Problem]
21
+
22
+ # Every response value but Skyward::API::Responses::Created, which carries a type of its own.
23
+ RESPONSES = [
24
+ Skyward::API::Responses::NoContent,
25
+ *PROBLEMS.keys,
26
+ Skyward::API::Responses::Redirect
27
+ ].freeze #: Array[Class]
28
+
29
+ UNTYPED = Skyward::Core::Types::Scalar.new(name: :untyped) #: Skyward::Core::Types::Scalar
30
+
31
+ # @rbs @label: String
32
+ # @rbs @writer: Writers::Writer
33
+
34
+ # @rbs returns: Array[Skyward::API::Routing::Router::returned]
35
+ # @rbs label: String
36
+ # @rbs return: void
37
+ def initialize(returns, label:)
38
+ @label = label
39
+ @writer = Writers.union(returns.map { |member| compile(member) })
40
+ freeze
41
+ end
42
+
43
+ # The whole body is written before anything is answered, so a value that doesn't fit sends none of it.
44
+ # @rbs value: untyped
45
+ # @rbs return: Skyward::API::rack
46
+ def call(value)
47
+ response = @writer.write.call(value, "")
48
+ case response
49
+ when Writers::Misfit then raise Skyward::API::ReturnTypeError, message(response)
50
+ else response
51
+ end
52
+ end
53
+
54
+ private
55
+
56
+ # @rbs member: Skyward::API::Routing::Router::returned
57
+ # @rbs return: Writers::Writer
58
+ def compile(member)
59
+ case member
60
+ when Skyward::API::Routing::Router::Created then created(Writers.writer(member.type))
61
+ when Skyward::API::Routing::Router::Response then response(member.klass)
62
+ when Skyward::API::Routing::Router::Rack then rack
63
+ when UNTYPED then untyped
64
+ else ok(Writers.writer(member))
65
+ end
66
+ end
67
+
68
+ # Untyped code can return any response value.
69
+ # @rbs return: Writers::Writer
70
+ def untyped
71
+ writer = Writers.writer(UNTYPED)
72
+ responses = [created(writer), *RESPONSES.map { |klass| response(klass) }, ok(writer)]
73
+ Writers.union(responses).with(name: "untyped")
74
+ end
75
+
76
+ # @rbs writer: Writers::Writer
77
+ # @rbs return: Writers::Writer
78
+ def ok(writer)
79
+ writer.with(write: ->(value, at) { json(writer.write.call(value, at), 200, JSON_TYPE.dup) })
80
+ end
81
+
82
+ # @rbs writer: Writers::Writer
83
+ # @rbs return: Writers::Writer
84
+ def created(writer)
85
+ Writers.checked(
86
+ "Skyward::API::Responses::Created[#{writer.name}]",
87
+ ->(given) { given.is_a?(Skyward::API::Responses::Created) },
88
+ lambda do |given, at|
89
+ json(writer.write.call(given.value, "#{at}.value"), 201, { **JSON_TYPE, **given.headers })
90
+ end
91
+ )
92
+ end
93
+
94
+ # @rbs klass: Class
95
+ # @rbs return: Writers::Writer
96
+ def response(klass)
97
+ problem = PROBLEMS.fetch(klass, nil)
98
+ answer =
99
+ if problem then ->(given, _) { problem_response(problem, given) }
100
+ elsif klass == Skyward::API::Responses::Redirect then ->(given, _) { [given.status, { "location" => given.to, **given.headers }, []] }
101
+ else ->(given, _) { [204, given.headers.dup, []] }
102
+ end #: ^(untyped, String) -> Skyward::API::Assembly::Dispatcher::response
103
+ Writers.checked(klass.name.to_s, ->(given) { given.is_a?(klass) }, answer)
104
+ end
105
+
106
+ # @rbs return: Writers::Writer
107
+ def rack
108
+ Writers.checked(
109
+ "Skyward::API::rack",
110
+ ->(given) { given.is_a?(Array) && given.size == 3 && given[0].is_a?(Integer) && given[1].is_a?(Hash) },
111
+ ->(given, _) { given }
112
+ )
113
+ end
114
+
115
+ # @rbs problem: Problem
116
+ # @rbs given: untyped
117
+ # @rbs return: Skyward::API::Assembly::Dispatcher::response
118
+ def problem_response(problem, given)
119
+ body = { type: "about:blank", title: problem.title, status: problem.status, detail: given.detail }.compact
120
+ [problem.status, { "content-type" => "application/problem+json", **given.headers }, [JSON.generate(body)]]
121
+ end
122
+
123
+ # @rbs written: untyped
124
+ # @rbs status: Integer
125
+ # @rbs headers: Hash[String, String]
126
+ # @rbs return: untyped
127
+ def json(written, status, headers)
128
+ written.is_a?(Writers::Misfit) ? written : [status, headers, [JSON.generate(written)]]
129
+ end
130
+
131
+ # @rbs misfit: Writers::Misfit
132
+ # @rbs return: String
133
+ def message(misfit)
134
+ return "#{@label} returned #{misfit.got}, which isn't #{misfit.expected}" if misfit.at.empty?
135
+
136
+ "#{@label} returned #{misfit.got} at #{misfit.at.delete_prefix(".")}, which isn't #{misfit.expected}, " \
137
+ "in its return type #{@writer.name}"
138
+ end
139
+ end
@@ -0,0 +1,160 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "stringio"
5
+
6
+ class Skyward::API::Test::Client
7
+ Response = Data.define(
8
+ :status, #: Integer
9
+ :headers, #: Hash[String, String | Array[String]]
10
+ :body, #: String
11
+ :json #: untyped
12
+ )
13
+
14
+ JSON_TYPE = %r{\A[^/;\s]+/(?:[^;\s]+\+)?json\s*(?:;|\z)}i #: Regexp
15
+
16
+ # Rack takes these two headers without the HTTP_ prefix the others get.
17
+ UNPREFIXED = %w[CONTENT_TYPE CONTENT_LENGTH].freeze #: Array[String]
18
+
19
+ # @rbs @app: Skyward::API::_RackApp
20
+
21
+ # @rbs (Skyward::API::_RackApp app) -> void
22
+ def initialize(app)
23
+ @app = app
24
+ freeze
25
+ end
26
+
27
+ # @rbs path: String
28
+ # @rbs json: untyped
29
+ # @rbs headers: Hash[String, String]
30
+ # @rbs cookies: Hash[String, String]
31
+ # @rbs return: Response
32
+ def get(path, json: nil, headers: {}, cookies: {})
33
+ request("GET", path, json, headers, cookies)
34
+ end
35
+
36
+ # @rbs path: String
37
+ # @rbs json: untyped
38
+ # @rbs headers: Hash[String, String]
39
+ # @rbs cookies: Hash[String, String]
40
+ # @rbs return: Response
41
+ def post(path, json: nil, headers: {}, cookies: {})
42
+ request("POST", path, json, headers, cookies)
43
+ end
44
+
45
+ # @rbs path: String
46
+ # @rbs json: untyped
47
+ # @rbs headers: Hash[String, String]
48
+ # @rbs cookies: Hash[String, String]
49
+ # @rbs return: Response
50
+ def put(path, json: nil, headers: {}, cookies: {})
51
+ request("PUT", path, json, headers, cookies)
52
+ end
53
+
54
+ # @rbs path: String
55
+ # @rbs json: untyped
56
+ # @rbs headers: Hash[String, String]
57
+ # @rbs cookies: Hash[String, String]
58
+ # @rbs return: Response
59
+ def patch(path, json: nil, headers: {}, cookies: {})
60
+ request("PATCH", path, json, headers, cookies)
61
+ end
62
+
63
+ # @rbs path: String
64
+ # @rbs json: untyped
65
+ # @rbs headers: Hash[String, String]
66
+ # @rbs cookies: Hash[String, String]
67
+ # @rbs return: Response
68
+ def delete(path, json: nil, headers: {}, cookies: {})
69
+ request("DELETE", path, json, headers, cookies)
70
+ end
71
+
72
+ # @rbs path: String
73
+ # @rbs json: untyped
74
+ # @rbs headers: Hash[String, String]
75
+ # @rbs cookies: Hash[String, String]
76
+ # @rbs return: Response
77
+ def head(path, json: nil, headers: {}, cookies: {})
78
+ request("HEAD", path, json, headers, cookies)
79
+ end
80
+
81
+ # @rbs path: String
82
+ # @rbs json: untyped
83
+ # @rbs headers: Hash[String, String]
84
+ # @rbs cookies: Hash[String, String]
85
+ # @rbs return: Response
86
+ def options(path, json: nil, headers: {}, cookies: {})
87
+ request("OPTIONS", path, json, headers, cookies)
88
+ end
89
+
90
+ private
91
+
92
+ # @rbs method: String
93
+ # @rbs path: String
94
+ # @rbs json: untyped
95
+ # @rbs headers: Hash[String, String]
96
+ # @rbs cookies: Hash[String, String]
97
+ # @rbs return: Response
98
+ def request(method, path, json, headers, cookies)
99
+ body = json.nil? ? "" : JSON.generate(json)
100
+ sent = body_headers(body).merge(cookie_header(cookies), headers)
101
+ status, response_headers, response_body = @app.call(env(method, path, body, sent))
102
+ text = read(response_body)
103
+ Response.new(status:, headers: response_headers, body: text, json: parse(response_headers["content-type"], text))
104
+ end
105
+
106
+ # @rbs body: String
107
+ # @rbs return: Hash[String, String]
108
+ def body_headers(body)
109
+ body.empty? ? {} : { "content-type" => "application/json", "content-length" => body.bytesize.to_s }
110
+ end
111
+
112
+ # @rbs cookies: Hash[String, String]
113
+ # @rbs return: Hash[String, String]
114
+ def cookie_header(cookies)
115
+ cookies.empty? ? {} : { "cookie" => cookies.map { |name, value| "#{name}=#{value}" }.join("; ") }
116
+ end
117
+
118
+ # @rbs method: String
119
+ # @rbs path: String
120
+ # @rbs body: String
121
+ # @rbs headers: Hash[String, String]
122
+ # @rbs return: Hash[String, untyped]
123
+ def env(method, path, body, headers)
124
+ path_info, _, query = path.partition("?")
125
+ {
126
+ "REQUEST_METHOD" => method,
127
+ "SCRIPT_NAME" => "",
128
+ "PATH_INFO" => path_info,
129
+ "QUERY_STRING" => query,
130
+ "SERVER_NAME" => "localhost",
131
+ "SERVER_PORT" => "80",
132
+ "SERVER_PROTOCOL" => "HTTP/1.1",
133
+ "rack.url_scheme" => "http",
134
+ "rack.input" => StringIO.new(body.b),
135
+ "rack.errors" => StringIO.new
136
+ }.merge(headers.to_h { |name, value| [env_key(name), value] })
137
+ end
138
+
139
+ # @rbs name: String
140
+ # @rbs return: String
141
+ def env_key(name)
142
+ key = name.upcase.tr("-", "_")
143
+ UNPREFIXED.include?(key) ? key : "HTTP_#{key}"
144
+ end
145
+
146
+ # @rbs body: untyped
147
+ # @rbs return: String
148
+ def read(body)
149
+ body.enum_for(:each).to_a.join
150
+ ensure
151
+ body.close if body.respond_to?(:close)
152
+ end
153
+
154
+ # @rbs content_type: untyped
155
+ # @rbs body: String
156
+ # @rbs return: untyped
157
+ def parse(content_type, body)
158
+ JSON.parse(body, symbolize_names: true) if JSON_TYPE.match?(content_type) && !body.empty?
159
+ end
160
+ end
@@ -0,0 +1,8 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Test
4
+ extend self
5
+
6
+ # @rbs (Skyward::API::_RackApp app) -> Client
7
+ def client(app) = Client.new(app)
8
+ end
@@ -2,6 +2,10 @@
2
2
 
3
3
  module Skyward
4
4
  class API
5
- VERSION = "0.1.0" #: String
5
+ # x-release-please-start-version
6
+
7
+ VERSION = "0.2.0" #: String
8
+
9
+ # x-release-please-end
6
10
  end
7
11
  end