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,164 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "uri"
5
+
6
+ class Skyward::API::Inputs
7
+ # @rbs!
8
+ # type refusal = :content_too_large | :unsupported_media_type
9
+ # type body = Coercer::result | refusal | nil
10
+
11
+ JSON_TYPE = %r{\A(?:application/json|[^/;\s]+/[^/;\s]+\+json)\s*(?:;|\z)}i #: Regexp
12
+
13
+ MALFORMED_QUERY = Coercer::Invalid.new(
14
+ errors: [Coercer::Error.new(at: "query", message: "is not a valid query string")]
15
+ ) #: Coercer::Invalid
16
+
17
+ INVALID_JSON = Coercer::Invalid.new(
18
+ errors: [Coercer::Error.new(at: "body", message: "is not valid JSON")]
19
+ ) #: Coercer::Invalid
20
+
21
+ # @rbs @keywords: Array[[Skyward::API::Routing::Router::Keyword, Coercer::t]]
22
+ # @rbs @providers: Array[Skyward::API::Routing::Router::Provider]
23
+ # @rbs @body: bool
24
+ # @rbs @request: bool
25
+ # @rbs @max_body_size: Integer
26
+
27
+ # @rbs keywords: Array[Skyward::API::Routing::Router::Keyword]
28
+ # @rbs providers: Array[Skyward::API::Routing::Router::Provider]
29
+ # @rbs max_body_size: Integer
30
+ # @rbs return: void
31
+ def initialize(keywords, providers:, max_body_size:)
32
+ requested, coerced = keywords.partition { |keyword| keyword.source == :request }
33
+ @keywords = coerced.map { |keyword| [keyword, Coercer.compile(keyword.type, strings: keyword.source != :body)] }
34
+ @providers = providers
35
+ @body = coerced.any? { |keyword| keyword.source == :body }
36
+ @request = requested.any?
37
+ @max_body_size = max_body_size
38
+ freeze
39
+ end
40
+
41
+ # Providers run first, so a caller they turn away learns nothing from the inputs' problems.
42
+ # @rbs env: Hash[String, untyped]
43
+ # @rbs params: Hash[Symbol, String]
44
+ # @rbs return: Coercer::result | refusal | Skyward::API::rack
45
+ def call(env, params)
46
+ request = Skyward::API::Request.new(env) if @request || @providers.any?
47
+ none = {} #: Hash[Symbol, untyped]
48
+ provided = request ? provide(@providers, request, none) : none
49
+ return provided if provided.is_a?(Array)
50
+
51
+ given = @request ? { **provided, request: } : provided
52
+ body = body(env) if @body
53
+ case body
54
+ when Symbol then body
55
+ else arguments(params, query(env["QUERY_STRING"].to_s), body, given)
56
+ end
57
+ end
58
+
59
+ private
60
+
61
+ # @rbs providers: Array[Skyward::API::Routing::Router::Provider]
62
+ # @rbs request: Skyward::API::Request
63
+ # @rbs values: Hash[Symbol, untyped]
64
+ # @rbs return: Hash[Symbol, untyped] | Skyward::API::rack
65
+ def provide(providers, request, values)
66
+ provider, *rest = providers
67
+ return values unless provider
68
+
69
+ value = provider.callable.call(request)
70
+ if Skyward::API::Serializer::RESPONSES.any? { |klass| value.is_a?(klass) }
71
+ provider.serializer.call(value)
72
+ else
73
+ provide(rest, request, { **values, provider.name => value })
74
+ end
75
+ end
76
+
77
+ # @rbs params: Hash[Symbol, String]
78
+ # @rbs query: Hash[String, String | Array[String]] | Coercer::Invalid
79
+ # @rbs body: Coercer::result?
80
+ # @rbs given: Hash[Symbol, untyped]
81
+ # @rbs return: Coercer::result
82
+ def arguments(params, query, body, given)
83
+ coerced = @keywords.filter_map { |keyword, coercer| argument(keyword, coercer, params, query, body) }
84
+ results = [*coerced, *given.map { |name, value| [name, Coercer::Ok.new(value:)] }]
85
+ combined = Coercer.combine(results.to_h)
86
+ case combined
87
+ # A malformed query string is every query keyword's error, but one problem,
88
+ # and each keyword can find up to MAX_ERRORS.
89
+ when Coercer::Invalid
90
+ combined.with(errors: combined.errors.uniq.first(Coercer::MAX_ERRORS))
91
+ else combined
92
+ end
93
+ end
94
+
95
+ # @rbs keyword: Skyward::API::Routing::Router::Keyword
96
+ # @rbs coercer: Coercer::t
97
+ # @rbs params: Hash[Symbol, String]
98
+ # @rbs query: Hash[String, String | Array[String]] | Coercer::Invalid
99
+ # @rbs body: Coercer::result?
100
+ # @rbs return: [Symbol, Coercer::result]?
101
+ def argument(keyword, coercer, params, query, body)
102
+ name = keyword.name
103
+ at = keyword.source == :body ? "body" : "#{keyword.source}.#{name}"
104
+ raw =
105
+ case keyword.source
106
+ when :path then Coercer::Ok.new(value: params.fetch(name))
107
+ when :query then from_query(query, name.to_s)
108
+ else body
109
+ end
110
+ result =
111
+ case raw
112
+ when Coercer::Ok then coercer.call(raw.value, at)
113
+ when Coercer::Invalid then raw
114
+ else Coercer.absent(keyword.type, keyword.required, at)
115
+ end
116
+ [name, result] if result
117
+ end
118
+
119
+ # @rbs query: Hash[String, String | Array[String]] | Coercer::Invalid
120
+ # @rbs key: String
121
+ # @rbs return: Coercer::result?
122
+ def from_query(query, key)
123
+ case query
124
+ when Coercer::Invalid then query
125
+ else (Coercer::Ok.new(value: query.fetch(key)) if query.key?(key))
126
+ end
127
+ end
128
+
129
+ # @rbs string: String
130
+ # @rbs return: Hash[String, String | Array[String]] | Coercer::Invalid
131
+ def query(string)
132
+ URI.decode_www_form(string).group_by(&:first).transform_values do |named|
133
+ named.size == 1 ? named.fetch(0).last : named.map(&:last)
134
+ end
135
+ # URI.decode_www_form raises for a byte outside ASCII, which a client can send unescaped.
136
+ rescue ArgumentError
137
+ MALFORMED_QUERY
138
+ end
139
+
140
+ # @rbs env: Hash[String, untyped]
141
+ # @rbs return: body
142
+ def body(env)
143
+ return :content_too_large if env["CONTENT_LENGTH"].to_i > @max_body_size
144
+
145
+ # One byte past the limit shows the body runs past it, without reading the rest.
146
+ text = env["rack.input"]&.read(@max_body_size + 1).to_s
147
+ return :content_too_large if text.bytesize > @max_body_size
148
+ return if text.empty?
149
+ return :unsupported_media_type unless JSON_TYPE.match?(env["CONTENT_TYPE"].to_s)
150
+
151
+ parse(String.new(text, encoding: Encoding::UTF_8))
152
+ end
153
+
154
+ # @rbs text: String
155
+ # @rbs return: Coercer::result
156
+ def parse(text)
157
+ # JSON.parse lets through bytes that aren't UTF-8, which JSON forbids.
158
+ return INVALID_JSON unless text.valid_encoding?
159
+
160
+ Coercer::Ok.new(value: JSON.parse(text))
161
+ rescue JSON::ParserError
162
+ INVALID_JSON
163
+ end
164
+ end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Middleware::LineLogger
4
+ # @rbs @io: IO
5
+
6
+ # @rbs io: IO
7
+ # @rbs return: void
8
+ def initialize(io)
9
+ @io = io
10
+ freeze
11
+ end
12
+
13
+ # @rbs message: String
14
+ # @rbs return: void
15
+ def info(message)
16
+ @io.write("#{message}\n")
17
+ # $stdout is block-buffered when it isn't a terminal, which would hold lines back from a log collector.
18
+ @io.flush
19
+ end
20
+ end
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Skyward::API::Middleware::RequestId
4
+ # Visible ASCII only, so a client can't put a space or a line break in the logs.
5
+ VALID = /\A[!-~]{1,200}\z/ #: Regexp
6
+
7
+ # @rbs @app: Skyward::API::_RackApp
8
+ # @rbs @generate: ^() -> String
9
+
10
+ # @rbs (Skyward::API::_RackApp app, generate: ^() -> String) -> void
11
+ def initialize(app, generate:)
12
+ @app = app
13
+ @generate = generate
14
+ freeze
15
+ end
16
+
17
+ # @rbs env: Hash[String, untyped]
18
+ # @rbs return: Skyward::API::rack_response
19
+ def call(env)
20
+ incoming = env["HTTP_X_REQUEST_ID"]
21
+ # Matched as binary, because Regexp#match? raises on a String that isn't valid UTF-8.
22
+ id = VALID.match?(incoming&.b) ? incoming : @generate.call
23
+ status, headers, body = @app.call(env.merge("skyward.request_id" => id))
24
+ [status, headers.merge("x-request-id" => id), body]
25
+ end
26
+ end
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ # Time#iso8601 is core only from Ruby 3.4.
5
+ require "time"
6
+
7
+ class Skyward::API::Middleware::RequestLog
8
+ # @rbs @app: Skyward::API::_RackApp
9
+ # @rbs @logger: Skyward::API::_Logger
10
+ # @rbs @now: ^() -> Time
11
+ # @rbs @clock_ms: ^() -> Float
12
+
13
+ # @rbs (Skyward::API::_RackApp app, logger: Skyward::API::_Logger, now: ^() -> Time, clock_ms: ^() -> Float) -> void
14
+ def initialize(app, logger:, now:, clock_ms:)
15
+ @app = app
16
+ @logger = logger
17
+ @now = now
18
+ @clock_ms = clock_ms
19
+ freeze
20
+ end
21
+
22
+ # @rbs env: Hash[String, untyped]
23
+ # @rbs return: Skyward::API::rack_response
24
+ def call(env)
25
+ time = @now.call.getutc.iso8601(3)
26
+ # Read before the app runs, because middleware can rewrite the env in place.
27
+ method = env["REQUEST_METHOD"]
28
+ # Rack's path is raw bytes from the client, and JSON.generate raises on invalid UTF-8.
29
+ path = String.new("#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}", encoding: Encoding::UTF_8).scrub
30
+ started = @clock_ms.call
31
+ response = @app.call(env)
32
+ @logger.info(
33
+ JSON.generate(
34
+ {
35
+ time:,
36
+ method:,
37
+ path:,
38
+ status: response.first,
39
+ duration_ms: (@clock_ms.call - started).round(2),
40
+ request_id: env["skyward.request_id"]
41
+ }
42
+ )
43
+ )
44
+ response
45
+ end
46
+ end
@@ -0,0 +1,81 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ class Skyward::API::Middleware::Rescue
6
+ # @rbs @app: Skyward::API::_RackApp
7
+ # @rbs @logger: Skyward::API::_Logger?
8
+ # @rbs @on_error: Skyward::API::_OnError?
9
+ # @rbs @development: bool
10
+
11
+ # @rbs (Skyward::API::_RackApp app, logger: Skyward::API::_Logger?, on_error: Skyward::API::_OnError?,
12
+ # development: bool) -> void
13
+ def initialize(app, logger:, on_error:, development:)
14
+ @app = app
15
+ @logger = logger
16
+ @on_error = on_error
17
+ @development = development
18
+ freeze
19
+ end
20
+
21
+ # @rbs env: Hash[String, untyped]
22
+ # @rbs return: Skyward::API::rack_response
23
+ def call(env)
24
+ # Read before the app runs, because middleware can rewrite the env in place.
25
+ verb = env["REQUEST_METHOD"]
26
+ @app.call(env)
27
+ rescue StandardError => e
28
+ request_id = env["skyward.request_id"]
29
+ log(e, request_id)
30
+ report(e, env, request_id)
31
+ body = verb == "HEAD" ? [] : [JSON.generate(problem(e, request_id))] #: Array[String]
32
+ [500, { "content-type" => "application/problem+json" }, body]
33
+ end
34
+
35
+ private
36
+
37
+ # @rbs exception: StandardError
38
+ # @rbs request_id: String?
39
+ # @rbs return: void
40
+ def log(exception, request_id)
41
+ @logger&.info(
42
+ JSON.generate(
43
+ {
44
+ level: "error",
45
+ request_id:,
46
+ class: exception.class.name,
47
+ message: message(exception),
48
+ backtrace: exception.backtrace
49
+ }
50
+ )
51
+ )
52
+ end
53
+
54
+ # @rbs exception: StandardError
55
+ # @rbs env: Hash[String, untyped]
56
+ # @rbs request_id: String?
57
+ # @rbs return: void
58
+ def report(exception, env, request_id)
59
+ @on_error&.call(exception, env)
60
+ rescue StandardError => e
61
+ log(e, request_id)
62
+ end
63
+
64
+ # @rbs exception: StandardError
65
+ # @rbs request_id: String?
66
+ # @rbs return: Hash[Symbol, untyped]
67
+ def problem(exception, request_id)
68
+ problem = { type: "about:blank", title: "Internal Server Error", status: 500, request_id: }
69
+ # An exception's message can carry data, so only development shows it.
70
+ return problem unless @development
71
+
72
+ { **problem, detail: "#{exception.class}: #{message(exception)}", backtrace: exception.backtrace }
73
+ end
74
+
75
+ # @rbs exception: StandardError
76
+ # @rbs return: String
77
+ def message(exception)
78
+ # A message can interpolate client path bytes, and JSON.generate raises on invalid UTF-8.
79
+ String.new(exception.message, encoding: Encoding::UTF_8).scrub
80
+ end
81
+ end
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Middleware
4
+ end
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "cgi/escape"
4
+
5
+ module Skyward::API::OpenAPI::Docs
6
+ extend self
7
+
8
+ PATH = "/docs" #: String
9
+
10
+ HTML_TYPE = "text/html; charset=utf-8" #: String
11
+
12
+ SCALAR_URL = "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.75.1/dist/browser/standalone.js" #: String
13
+
14
+ # Recompute from the file whenever SCALAR_URL's version changes.
15
+ SCALAR_INTEGRITY = "sha384-G+2Q2i9l3PPfmYkk0b4BAIUrs7xb/DNaTL1wCYYab4c9dIKlCyiqzC0Qx3eq9Wf6" #: String
16
+
17
+ # @rbs title: String
18
+ # @rbs scalar_url: String
19
+ # @rbs return: String
20
+ def page(title:, scalar_url:)
21
+ integrity = %( integrity="#{SCALAR_INTEGRITY}" crossorigin="anonymous") if scalar_url == SCALAR_URL
22
+ # The document's URL is relative, so it's found beside /docs under whatever
23
+ # prefix a larger Rack app mounts this one at.
24
+ <<~HTML.freeze
25
+ <!doctype html>
26
+ <html lang="en">
27
+ <head>
28
+ <meta charset="utf-8">
29
+ <meta name="viewport" content="width=device-width, initial-scale=1">
30
+ <title>#{CGI.escapeHTML(title)}</title>
31
+ </head>
32
+ <body>
33
+ <script id="api-reference" data-url="openapi.json" data-configuration='{"withDefaultFonts":false}'></script>
34
+ <script src="#{CGI.escapeHTML(scalar_url)}"#{integrity}></script>
35
+ </body>
36
+ </html>
37
+ HTML
38
+ end
39
+ end