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,121 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ class Skyward::API::Assembly::Dispatcher
6
+ # @rbs! type response = [Integer, Hash[String, String], Array[String]]
7
+
8
+ INPUT_TITLES = { 413 => "Content Too Large", 415 => "Unsupported Media Type" }.freeze #: Hash[Integer, String]
9
+
10
+ Document = Data.define(
11
+ :type, #: String
12
+ :body #: String
13
+ )
14
+
15
+ # @rbs @router: Skyward::API::Routing::Router
16
+ # @rbs @static: Skyward::API::Assembly::Static
17
+ # @rbs @stack: Skyward::API::_RackApp
18
+ # @rbs @documents: Hash[String, Document]
19
+
20
+ # @rbs router: Skyward::API::Routing::Router
21
+ # @rbs static: Skyward::API::Assembly::Static
22
+ # @rbs middleware: Array[Skyward::API::Assembly::Builder::Use]
23
+ # @rbs documents: Hash[String, Document]
24
+ # @rbs return: void
25
+ def initialize(router, static, middleware, documents)
26
+ @router = router
27
+ @static = static
28
+ @documents = documents
29
+ innermost = method(:route) #: Skyward::API::_RackApp
30
+ @stack = middleware.reverse.reduce(innermost) do |app, use|
31
+ use.middleware.new(app, *use.args, **use.kwargs, &use.block)
32
+ end
33
+ # Only the app is frozen, not the middleware: some keep state of their
34
+ # own, like the logger rack-cors picks on its first request.
35
+ freeze
36
+ end
37
+
38
+ # @rbs env: Hash[String, untyped]
39
+ # @rbs return: Skyward::API::rack_response
40
+ def call(env) = @stack.call(env)
41
+
42
+ private
43
+
44
+ # @rbs env: Hash[String, untyped]
45
+ # @rbs return: Skyward::API::rack
46
+ def route(env)
47
+ verb = env["REQUEST_METHOD"]
48
+ path = env["PATH_INFO"]
49
+ # Boot refuses a route or a file at a document's path, but a path parameter can still match it, so it comes first.
50
+ status, headers, body = served(verb, path) || routed(env, verb, path)
51
+ [status, headers, verb == "HEAD" ? dropped(body) : body]
52
+ end
53
+
54
+ # @rbs verb: String
55
+ # @rbs path: String
56
+ # @rbs return: response?
57
+ def served(verb, path)
58
+ document = @documents[path]
59
+ return unless document && %w[GET HEAD].include?(verb)
60
+
61
+ [200, { "content-type" => document.type }, [document.body]]
62
+ end
63
+
64
+ # @rbs env: Hash[String, untyped]
65
+ # @rbs verb: String
66
+ # @rbs path: String
67
+ # @rbs return: Skyward::API::rack
68
+ def routed(env, verb, path)
69
+ match = @router.match(verb, path)
70
+ match ? respond(match, env) : @static.call(env) || unmatched(verb, @router.allowed(path))
71
+ end
72
+
73
+ # @rbs match: Skyward::API::Routing::Router::Match
74
+ # @rbs env: Hash[String, untyped]
75
+ # @rbs return: Skyward::API::rack
76
+ def respond(match, env)
77
+ inputs = match.inputs.call(env, match.params)
78
+ case inputs
79
+ when Skyward::API::Inputs::Coercer::Ok then match.serializer.call(match.api.public_send(match.to, **inputs.value))
80
+ when Skyward::API::Inputs::Coercer::Invalid
81
+ problem(422, "Unprocessable Content", errors: inputs.errors.map(&:to_h))
82
+ when :content_too_large then problem(413, INPUT_TITLES.fetch(413))
83
+ when Array then inputs
84
+ else problem(415, INPUT_TITLES.fetch(415))
85
+ end
86
+ end
87
+
88
+ # A server closes the body it sends, so one that's never sent is closed here.
89
+ # @rbs body: untyped
90
+ # @rbs return: Array[String]
91
+ def dropped(body)
92
+ body.close if body.respond_to?(:close)
93
+ []
94
+ end
95
+
96
+ # @rbs verb: String
97
+ # @rbs allowed: Array[String]
98
+ # @rbs return: response
99
+ def unmatched(verb, allowed)
100
+ return problem(404, "Not Found") if allowed.empty?
101
+
102
+ allow = { "allow" => allowed.join(", ") }
103
+ verb == "OPTIONS" ? [204, allow, []] : problem(405, "Method Not Allowed", allow)
104
+ end
105
+
106
+ # @rbs status: Integer
107
+ # @rbs title: String
108
+ # @rbs headers: Hash[String, String]
109
+ # @rbs **members: untyped
110
+ # @rbs return: response
111
+ def problem(status, title, headers = {}, **members)
112
+ body = { type: "about:blank", title:, status:, **members }
113
+ json(status, { "content-type" => "application/problem+json", **headers }, body)
114
+ end
115
+
116
+ # @rbs status: Integer
117
+ # @rbs headers: Hash[String, String]
118
+ # @rbs value: untyped
119
+ # @rbs return: response
120
+ def json(status, headers, value) = [status, headers, [JSON.generate(value)]]
121
+ end
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "time"
4
+
5
+ class Skyward::API::Assembly::Static
6
+ TYPES = {
7
+ ".avif" => "image/avif",
8
+ ".css" => "text/css",
9
+ ".csv" => "text/csv",
10
+ ".gif" => "image/gif",
11
+ ".htm" => "text/html",
12
+ ".html" => "text/html",
13
+ ".ico" => "image/vnd.microsoft.icon",
14
+ ".jpeg" => "image/jpeg",
15
+ ".jpg" => "image/jpeg",
16
+ ".js" => "text/javascript",
17
+ ".json" => "application/json",
18
+ ".map" => "application/json",
19
+ ".mjs" => "text/javascript",
20
+ ".pdf" => "application/pdf",
21
+ ".png" => "image/png",
22
+ ".svg" => "image/svg+xml",
23
+ ".txt" => "text/plain",
24
+ ".wasm" => "application/wasm",
25
+ ".webmanifest" => "application/manifest+json",
26
+ ".webp" => "image/webp",
27
+ ".woff" => "font/woff",
28
+ ".woff2" => "font/woff2",
29
+ ".xml" => "application/xml"
30
+ }.freeze #: Hash[String, String]
31
+
32
+ # @rbs @statics: Array[Skyward::API::Assembly::Builder::Static]
33
+
34
+ # @rbs statics: Array[Skyward::API::Assembly::Builder::Static]
35
+ # @rbs return: void
36
+ def initialize(statics)
37
+ @statics = statics.map { |static| static.with(prefix: static.prefix.delete_suffix("/")) }
38
+ end
39
+
40
+ # @rbs env: Hash[String, untyped]
41
+ # @rbs return: Skyward::API::Assembly::Dispatcher::response?
42
+ def call(env)
43
+ return unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
44
+
45
+ file = file(env["PATH_INFO"])
46
+ serve(file, env) if file
47
+ end
48
+
49
+ # @rbs path: String
50
+ # @rbs return: String?
51
+ def file(path) = @statics.lazy.filter_map { |static| find(static, path) }.first
52
+
53
+ private
54
+
55
+ # @rbs static: Skyward::API::Assembly::Builder::Static
56
+ # @rbs path: String
57
+ # @rbs return: String?
58
+ def find(static, path)
59
+ return unless path == static.prefix || path.start_with?("#{static.prefix}/")
60
+
61
+ rest = path.delete_prefix(static.prefix)
62
+ rest = "#{rest}index.html" if rest.empty? || rest.end_with?("/")
63
+ names = rest.split("/").map { |segment| Skyward::API::Routing::PercentEncoding.decode(segment) }
64
+ # Each segment is decoded after splitting, so an escaped / stays inside a
65
+ # name, where joining would make it a separator. File raises on a NUL.
66
+ return if names.any? { |name| name == ".." || name.include?("/") || name.include?("\0") }
67
+
68
+ # File.file? follows a symlink under from: whoever deployed it put it there.
69
+ file = File.join(static.from, *names)
70
+ file if File.file?(file)
71
+ end
72
+
73
+ # @rbs file: String
74
+ # @rbs env: Hash[String, untyped]
75
+ # @rbs return: Skyward::API::Assembly::Dispatcher::response
76
+ def serve(file, env)
77
+ stat = File.stat(file)
78
+ etag = etag(stat)
79
+ validators = { "last-modified" => stat.mtime.httpdate, "etag" => etag, "cache-control" => "no-cache" }
80
+ return [304, validators, []] if fresh?(env, etag, stat.mtime)
81
+
82
+ type = TYPES.fetch(File.extname(file).downcase(:ascii), "application/octet-stream")
83
+ headers = { "content-type" => type, "content-length" => stat.size.to_s, **validators }
84
+ [200, headers, [File.binread(file)]]
85
+ end
86
+
87
+ # @rbs stat: File::Stat
88
+ # @rbs return: String
89
+ def etag(stat)
90
+ nanoseconds = (stat.mtime.to_i * 1_000_000_000) + stat.mtime.nsec
91
+ %("#{nanoseconds.to_s(16)}-#{stat.size.to_s(16)}")
92
+ end
93
+
94
+ # If-Modified-Since only counts without If-None-Match (RFC 9110, 13.2.2),
95
+ # and to the second, the precision of last-modified.
96
+ # @rbs env: Hash[String, untyped]
97
+ # @rbs etag: String
98
+ # @rbs modified: Time
99
+ # @rbs return: bool
100
+ def fresh?(env, etag, modified)
101
+ tags = env["HTTP_IF_NONE_MATCH"]
102
+ return tags.b.split(",").any? { |tag| ["*", etag].include?(tag.strip.delete_prefix("W/")) } if tags
103
+
104
+ since = http_date(env["HTTP_IF_MODIFIED_SINCE"])
105
+ since ? since.to_i >= modified.to_i : false
106
+ end
107
+
108
+ # @rbs value: String?
109
+ # @rbs return: Time?
110
+ def http_date(value)
111
+ Time.httpdate(value) if value
112
+ rescue ArgumentError
113
+ nil
114
+ end
115
+ end
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::Assembly
4
+ end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::CLI::AppFile
4
+ extend self
5
+
6
+ FILE = "app.rb" #: String
7
+
8
+ ASSIGNMENT = "App = Skyward.app { ... }" #: String
9
+
10
+ # @rbs (String directory, out: _Writer, kernel: singleton(Kernel)) { (Skyward::API::Assembly::Application) -> String }
11
+ # -> void
12
+ def run(directory, out:, kernel:, &)
13
+ app = load(directory)
14
+ case app
15
+ when String then kernel.abort(app)
16
+ else out.write(yield app)
17
+ end
18
+ # Booting the app raises it, and so can what's made from the app, such as
19
+ # an OpenAPI document with two operations of one ID.
20
+ rescue Skyward::Core::BootError => e
21
+ kernel.abort(e.message)
22
+ end
23
+
24
+ # @rbs directory: String
25
+ # @rbs return: Skyward::API::Assembly::Application | String
26
+ def load(directory)
27
+ path = File.join(directory, FILE)
28
+ unless File.file?(path)
29
+ return "skyward: no #{FILE} in #{directory}. Run skyward where your app's #{FILE} assigns #{ASSIGNMENT}."
30
+ end
31
+
32
+ require path
33
+ app = Object.const_get(:App) if Object.const_defined?(:App)
34
+ return app if app.is_a?(Skyward::API::Assembly::Application)
35
+
36
+ "skyward: #{path} doesn't assign a Skyward app to App. Assign #{ASSIGNMENT}."
37
+ end
38
+ end
@@ -0,0 +1,145 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "tmpdir"
4
+
5
+ module Skyward::API::CLI::Check
6
+ extend self
7
+
8
+ # @rbs! type capture = ^(Hash[String, String] env, Array[String] command, String chdir) -> [String, bool]
9
+
10
+ Outcome = Data.define(
11
+ :passed, #: bool
12
+ :detail #: String
13
+ )
14
+
15
+ PASSED = Outcome.new(passed: true, detail: "") #: Outcome
16
+
17
+ GENERATED = "sig/generated" #: String
18
+
19
+ STEEPFILE = "Steepfile" #: String
20
+
21
+ # None holds the app's contract: its tests, its installed gems and scratch.
22
+ UNCHECKED = %w[test spec vendor tmp].freeze #: Array[String]
23
+
24
+ # The strict boot's own Ruby runs it, so the forced strict mode, the app's
25
+ # side effects and an exit or crash stay out of skyward check. The require
26
+ # lives here because a `-r` on the command line runs before RUBYOPT's
27
+ # `-rbundler/setup` on newer Rubies, before the bundle's gems are loadable.
28
+ BOOT = 'require "skyward/api"; ' \
29
+ 'Skyward::API::CLI::AppFile.run(Dir.pwd, out: $stdout, kernel: Kernel) { "" }' #: String
30
+
31
+ INSTALL_RBS_INLINE = "rbs-inline isn't installed. Add `gem \"rbs-inline\", require: false` to the Gemfile " \
32
+ "and run `bundle install`.\n" #: String
33
+
34
+ INSTALL_STEEP = "Steep isn't installed. Add `gem \"steep\", require: false` to the Gemfile " \
35
+ "and run `bundle install`.\n" #: String
36
+
37
+ # @rbs (String directory, out: _Writer, capture: capture, rbs_inline: String?, steep: String?) -> Integer
38
+ def run(directory, out:, capture:, rbs_inline:, steep:)
39
+ checks = {
40
+ "Signatures" => -> { signatures(directory, capture:, rbs_inline:) },
41
+ "Strict boot" => -> { strict_boot(directory, capture:) },
42
+ "Steep" => -> { type_check(directory, capture:, steep:) }
43
+ }
44
+ passed = checks.map do |name, check|
45
+ outcome = check.call
46
+ out.write("#{name}: #{outcome.passed ? "passed" : "failed"}\n", outcome.detail)
47
+ outcome.passed
48
+ end
49
+ passed.all? ? 0 : 1
50
+ end
51
+
52
+ # @rbs directory: String
53
+ # @rbs capture: capture
54
+ # @rbs rbs_inline: String?
55
+ # @rbs return: Outcome
56
+ def signatures(directory, capture:, rbs_inline:)
57
+ return failed(INSTALL_RBS_INLINE) unless rbs_inline
58
+
59
+ paths = sources(directory)
60
+ generate = "bundle exec rbs-inline --output=#{GENERATED} #{paths.join(" ")}"
61
+ generated = File.join(directory, GENERATED)
62
+ unless File.directory?(generated)
63
+ return failed("There's no #{GENERATED}. Run `#{generate}` and commit the result.\n")
64
+ end
65
+
66
+ Dir.mktmpdir("skyward-check") do |output|
67
+ log, ok = capture.call({}, [Gem.ruby, rbs_inline, "--output=#{output}", *paths], directory)
68
+ next failed(log) unless ok
69
+
70
+ stale = differences(rbs_files(generated), rbs_files(output))
71
+ next PASSED if stale.empty?
72
+
73
+ failed(
74
+ [
75
+ "#{GENERATED} doesn't match what rbs-inline generates from the app's Ruby:\n",
76
+ *stale.map { |line| " #{line}\n" },
77
+ "Run `rm -rf #{GENERATED} && #{generate}` and commit the result.\n"
78
+ ].join
79
+ )
80
+ end
81
+ end
82
+
83
+ # @rbs directory: String
84
+ # @rbs capture: capture
85
+ # @rbs return: Outcome
86
+ def strict_boot(directory, capture:)
87
+ output, ok = capture.call({ "SKYWARD_STRICT" => "1" }, [Gem.ruby, "-e", BOOT], directory)
88
+ Outcome.new(passed: ok, detail: output)
89
+ end
90
+
91
+ # @rbs directory: String
92
+ # @rbs capture: capture
93
+ # @rbs steep: String?
94
+ # @rbs return: Outcome
95
+ def type_check(directory, capture:, steep:)
96
+ return failed(INSTALL_STEEP) unless steep
97
+ unless File.file?(File.join(directory, STEEPFILE))
98
+ return failed(
99
+ "There's no #{STEEPFILE} in #{directory}. Add one that checks the app's Ruby: " \
100
+ "`bundle exec steep init` writes one to start from.\n"
101
+ )
102
+ end
103
+
104
+ # Steep otherwise checks through any language server it finds running,
105
+ # which can report stale results.
106
+ output, ok = capture.call({}, [Gem.ruby, steep, "check", "--no-daemon"], directory)
107
+ Outcome.new(passed: ok, detail: output)
108
+ end
109
+
110
+ private
111
+
112
+ # @rbs detail: String
113
+ # @rbs return: Outcome
114
+ def failed(detail) = Outcome.new(passed: false, detail:)
115
+
116
+ # @rbs directory: String
117
+ # @rbs return: Array[String]
118
+ def sources(directory)
119
+ roots = Dir.glob("*/", base: directory).map { |root| root.delete_suffix("/") } - UNCHECKED
120
+ files = Dir.glob("*.rb", base: directory)
121
+ [*files, *roots.reject { |root| Dir.glob("#{root}/**/*.rb", base: directory).empty? }].sort
122
+ end
123
+
124
+ # @rbs directory: String
125
+ # @rbs return: Hash[String, String]
126
+ def rbs_files(directory)
127
+ Dir.glob("**/*.rbs", base: directory).to_h { |file| [file, File.read(File.join(directory, file))] }
128
+ end
129
+
130
+ # @rbs current: Hash[String, String]
131
+ # @rbs expected: Hash[String, String]
132
+ # @rbs return: Array[String]
133
+ def differences(current, expected)
134
+ (current.keys | expected.keys).sort.filter_map do |file|
135
+ path = "#{GENERATED}/#{file}"
136
+ if !current.key?(file)
137
+ "#{path} is missing"
138
+ elsif !expected.key?(file)
139
+ "#{path} isn't generated from any file"
140
+ elsif current[file] != expected[file]
141
+ "#{path} is out of date"
142
+ end
143
+ end
144
+ end
145
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::CLI::Executable
4
+ extend self
5
+
6
+ # Under Bundler, Gem.find_files and Gem.bin_path see only the bundle's gems,
7
+ # so a gem installed outside the app's bundle isn't found. Checking first
8
+ # spares rescuing the error bin_path raises for a missing gem.
9
+ # @rbs name: String
10
+ # @rbs feature: String
11
+ # @rbs return: String?
12
+ def find(name, feature: name)
13
+ Gem.bin_path(name, name) unless Gem.find_files("#{feature}.rb").empty?
14
+ end
15
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::CLI::Routes
4
+ extend self
5
+
6
+ GAP = 2 #: Integer
7
+
8
+ # @rbs endpoints: Array[Skyward::API::Routing::Router::Endpoint]
9
+ # @rbs return: String
10
+ def table(endpoints)
11
+ rows = endpoints.map do |endpoint|
12
+ [endpoint.verb, path(endpoint.pattern), handler(endpoint), endpoint.signature.gsub(/\s*\R\s*/, " ")]
13
+ end
14
+ widths = rows.transpose.map { |column| (column.map(&:length).max || 0) + GAP }
15
+ rows.map do |row|
16
+ *padded, signature = row
17
+ "#{padded.map.with_index { |cell, index| cell.ljust(widths.fetch(index)) }.join}#{signature}\n"
18
+ end.join
19
+ end
20
+
21
+ private
22
+
23
+ # @rbs pattern: Array[String | Symbol]
24
+ # @rbs return: String
25
+ def path(pattern) = pattern.map { |part| part.is_a?(Symbol) ? ":#{part}" : part }.join("/")
26
+
27
+ # @rbs endpoint: Skyward::API::Routing::Router::Endpoint
28
+ # @rbs return: String
29
+ def handler(endpoint) = "#{endpoint.api.class}##{endpoint.to}"
30
+ end
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ class Skyward::API::CLI::Serve::Reloader
6
+ INTERVAL = 0.5 #: Float
7
+
8
+ # @rbs @watch: ^() -> Hash[String, Time]
9
+ # @rbs @load: ^() -> Skyward::API::_RackApp
10
+ # @rbs @clock: ^() -> Float
11
+ # @rbs @mutex: Thread::Mutex
12
+ # @rbs @checked_at: Float
13
+ # @rbs @files: Hash[String, Time]
14
+ # @rbs @app: Skyward::API::_RackApp
15
+
16
+ # @rbs watch: ^() -> Hash[String, Time]
17
+ # @rbs load: ^() -> Skyward::API::_RackApp
18
+ # @rbs clock: ^() -> Float
19
+ # @rbs return: void
20
+ def initialize(watch:, load:, clock:)
21
+ @watch = watch
22
+ @load = load
23
+ @clock = clock
24
+ @mutex = Thread::Mutex.new
25
+ @checked_at = clock.call
26
+ @files = watch.call
27
+ @app = attempt
28
+ end
29
+
30
+ # The app is taken under the lock but called outside it, so a request in
31
+ # flight finishes on the app it started with.
32
+ # @rbs env: Hash[String, untyped]
33
+ # @rbs return: Skyward::API::rack_response
34
+ def call(env) = @mutex.synchronize { current }.call(env)
35
+
36
+ private
37
+
38
+ # @rbs return: Skyward::API::_RackApp
39
+ def current
40
+ now = @clock.call
41
+ return @app if now - @checked_at < INTERVAL
42
+
43
+ @checked_at = now
44
+ files = @watch.call
45
+ return @app if files == @files
46
+
47
+ @files = files
48
+ @app = attempt
49
+ end
50
+
51
+ # @rbs return: Skyward::API::_RackApp
52
+ def attempt
53
+ @load.call
54
+ # A SyntaxError or LoadError is a ScriptError, not a StandardError.
55
+ rescue StandardError, ScriptError => e
56
+ ->(env) { failure(e, env) } #: ^(Hash[String, untyped]) -> Skyward::API::rack_response
57
+ end
58
+
59
+ # The development 500 that Skyward::API::Middleware::Rescue answers, without a request
60
+ # ID: the app that assigns them is the one that failed to load.
61
+ # @rbs error: Exception
62
+ # @rbs env: Hash[String, untyped]
63
+ # @rbs return: Skyward::API::rack_response
64
+ def failure(error, env)
65
+ # A message can quote a source line's bytes, and JSON.generate raises on invalid UTF-8.
66
+ message = String.new(error.message, encoding: Encoding::UTF_8).scrub
67
+ problem = {
68
+ type: "about:blank",
69
+ title: "Internal Server Error",
70
+ status: 500,
71
+ detail: "#{error.class}: #{message}",
72
+ backtrace: error.backtrace
73
+ }
74
+ body = env["REQUEST_METHOD"] == "HEAD" ? [] : [JSON.generate(problem)] #: Array[String]
75
+ [500, { "content-type" => "application/problem+json" }, body]
76
+ end
77
+ end
@@ -0,0 +1,137 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Skyward::API::CLI::Serve
4
+ extend self
5
+
6
+ RACKUP = "#{__dir__}/serve.ru".freeze #: String
7
+
8
+ CONFIG = "config.ru" #: String
9
+
10
+ # Neither watched nor reloaded, and nor is any hidden directory: the app's
11
+ # gems can be installed under vendor/ or .bundle/.
12
+ IGNORED = %w[tmp log vendor node_modules].freeze #: Array[String]
13
+
14
+ WATCHED = "{*.rb,*.rbs,#{CONFIG}}".freeze #: String
15
+
16
+ # @rbs directory: String
17
+ # @rbs env: Hash[String, String]
18
+ # @rbs falcon: String?
19
+ # @rbs kernel: singleton(Kernel)
20
+ # @rbs return: void
21
+ def run(directory, env:, falcon:, kernel:)
22
+ unless File.file?(File.join(directory, CONFIG))
23
+ return kernel.abort("skyward: no config.ru in #{directory}. Run skyward serve where your app's config.ru is.")
24
+ end
25
+
26
+ unless falcon
27
+ return kernel.abort(
28
+ "skyward: Falcon isn't installed. Add `gem \"falcon\"` to the Gemfile and run `bundle install`, " \
29
+ "or run config.ru under any Rack server, such as Puma."
30
+ )
31
+ end
32
+
33
+ kernel.exec(
34
+ { "RACK_ENV" => env.fetch("RACK_ENV", "development") },
35
+ Gem.ruby,
36
+ falcon,
37
+ "serve",
38
+ "--bind",
39
+ "http://localhost:#{env.fetch("PORT", "9292")}",
40
+ "--count",
41
+ "1",
42
+ "--config",
43
+ RACKUP,
44
+ chdir: directory
45
+ )
46
+ end
47
+
48
+ # @rbs directory: String
49
+ # @rbs build: ^(String config) -> Skyward::API::_RackApp
50
+ # @rbs clock: ^() -> Float
51
+ # @rbs apis: ^() -> Array[singleton(Skyward::API)]
52
+ # @rbs features: Array[String]
53
+ # @rbs loaders: ^() -> Array[Zeitwerk::Loader]
54
+ # @rbs return: Reloader
55
+ def reloader(directory, build:, clock:, apis:, features:, loaders:)
56
+ Reloader.new(
57
+ watch: -> { watch(directory) },
58
+ load: lambda do
59
+ unload(directory, apis: apis.call, features:, loaders: loaders.call)
60
+ build.call(File.join(directory, CONFIG))
61
+ end,
62
+ clock:
63
+ )
64
+ end
65
+
66
+ # @rbs directory: String
67
+ # @rbs return: Hash[String, Time]
68
+ def watch(directory)
69
+ roots = Dir.glob("*/", base: directory).map { |root| root.delete_suffix("/") }.reject { |root| ignored?(root) }
70
+ files = Dir.glob([WATCHED, *roots.map { |root| "#{root}/**/#{WATCHED}" }], base: directory)
71
+ files.to_h { |file| [file, File.mtime(File.join(directory, file))] }
72
+ end
73
+
74
+ # @rbs directory: String
75
+ # @rbs apis: Array[singleton(Skyward::API)]
76
+ # @rbs features: Array[String]
77
+ # @rbs loaders: Array[Zeitwerk::Loader]
78
+ # @rbs return: void
79
+ def unload(directory, apis:, features:, loaders:)
80
+ app_loaders, other_loaders = loaders.partition do |loader|
81
+ dirs = loader.dirs
82
+ dirs.any? && dirs.all? { |dir| reloaded?(directory, dir) }
83
+ end
84
+ # Zeitwerk tracks what to unload only with reloading enabled, and it can't
85
+ # be enabled after setup, so the loader's classes could never be reloaded.
86
+ stuck = app_loaders.find { |loader| !loader.reloading_enabled? }
87
+ if stuck
88
+ raise Skyward::Core::BootError,
89
+ "skyward serve can't reload the Zeitwerk loader for #{stuck.dirs.join(", ")}. Call " \
90
+ "`loader.enable_reloading` before `loader.setup` in development, then restart skyward serve."
91
+ end
92
+
93
+ apis.select { |api| reloaded_api?(directory, api) }.each(&:clear_declarations)
94
+ features.reject! { |feature| reloaded?(directory, feature) }
95
+ # config.ru sets the app's loaders up again, and Zeitwerk refuses a second
96
+ # loader for a directory one still manages, so each is dropped for good.
97
+ # unregister is experimental, but it's what unload is documented to go with.
98
+ app_loaders.each do |loader|
99
+ # Finishes a setup that failed, so unload removes every autoload it
100
+ # defined, or raises what's still wrong. A set-up loader ignores it.
101
+ loader.setup
102
+ loader.unload
103
+ loader.unregister
104
+ end
105
+ other_loaders.each { |loader| loader.reload if loader.reloading_enabled? }
106
+ end
107
+
108
+ private
109
+
110
+ # @rbs directory: String
111
+ # @rbs api: singleton(Skyward::API)
112
+ # @rbs return: bool
113
+ def reloaded_api?(directory, api)
114
+ name = api.name
115
+ # const_source_location refuses the name of a class under an anonymous module.
116
+ return false if name.nil? || name.start_with?("#")
117
+ # A class left over from an earlier load keeps its name after its namespace
118
+ # is gone, and const_source_location raises for a missing namespace.
119
+ return false unless Object.const_defined?(name)
120
+
121
+ file, = Object.const_source_location(name)
122
+ file ? reloaded?(directory, file) : false
123
+ end
124
+
125
+ # @rbs directory: String
126
+ # @rbs path: String
127
+ # @rbs return: bool
128
+ def reloaded?(directory, path)
129
+ return false unless path == directory || path.start_with?("#{directory}/")
130
+
131
+ !ignored?(path.delete_prefix(directory).delete_prefix("/").partition("/").first)
132
+ end
133
+
134
+ # @rbs root: String
135
+ # @rbs return: bool
136
+ def ignored?(root) = root.start_with?(".") || IGNORED.include?(root)
137
+ end