skyward-api 0.4.0 → 0.4.1
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/LICENSE +21 -0
- data/README.md +48 -48
- data/lib/skyward/api/assembly/boot.rb +37 -37
- data/lib/skyward/api/assembly/builder.rb +2 -2
- data/lib/skyward/api/assembly/dispatcher.rb +12 -12
- data/lib/skyward/api/assembly/static.rb +36 -36
- data/lib/skyward/api/cli/app_file.rb +2 -2
- data/lib/skyward/api/cli/check.rb +9 -9
- data/lib/skyward/api/cli/routes.rb +2 -2
- data/lib/skyward/api/cli/serve/reloader.rb +6 -6
- data/lib/skyward/api/cli/serve.rb +15 -15
- data/lib/skyward/api/cli/serve.ru +2 -2
- data/lib/skyward/api/commands.rb +10 -10
- data/lib/skyward/api/endpoints/declarations.rb +2 -2
- data/lib/skyward/api/inputs/coercer.rb +19 -19
- data/lib/skyward/api/inputs.rb +9 -9
- data/lib/skyward/api/middleware/request_id.rb +3 -3
- data/lib/skyward/api/middleware/request_log.rb +5 -5
- data/lib/skyward/api/middleware/rescue.rb +7 -7
- data/lib/skyward/api/openapi/docs.rb +5 -5
- data/lib/skyward/api/openapi.rb +51 -51
- data/lib/skyward/api/request.rb +8 -8
- data/lib/skyward/api/routing/percent_encoding.rb +1 -1
- data/lib/skyward/api/routing/router.rb +68 -27
- data/lib/skyward/api/serializer/writers.rb +19 -19
- data/lib/skyward/api/serializer.rb +15 -15
- data/lib/skyward/api/test/client.rb +25 -25
- data/lib/skyward/api/version.rb +1 -1
- data/lib/skyward/api.rb +15 -15
- data/sig/generated/skyward/api/routing/router.rbs +52 -9
- metadata +5 -4
- /data/sig/{manual/zeitwerk/loader.rbs → _private/zeitwerk.rbs} +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ae83d4087ae6b30e2f71d46ccbe2411aa9b0eda9fb9e808668729ccd26285dc6
|
|
4
|
+
data.tar.gz: b0931995b0908395f024d9aafcfe52c361c722cc37c92374c76ed697a9f9108c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c0a5328e129791a84710b9a4a9e2a47194199af046e6a11d61252720cc6152fb6b59487a9472cc75897d3a222255994bf3cc7c333c90128a5dab56a31b2a176b
|
|
7
|
+
data.tar.gz: 98185ca66483e2f962be0c23750e2b6141d510a732234104cde6bb778a7671d5a301b31d66a71dd2099eb7d79cc5ce6ca7949dc90a43cc82cd1bf2c92926d531
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jake Bottrall
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
CHANGED
|
@@ -11,14 +11,14 @@ It's half of Skyward. The other half is [Skyward ORM](../skyward-orm/README.md),
|
|
|
11
11
|
|
|
12
12
|
```ruby
|
|
13
13
|
# config.ru
|
|
14
|
-
require
|
|
14
|
+
require 'skyward/api'
|
|
15
15
|
|
|
16
16
|
class Hello < Skyward::API
|
|
17
|
-
get
|
|
17
|
+
get '/hello/:name', to: :greet
|
|
18
18
|
|
|
19
|
-
def greet(name:, shout:
|
|
19
|
+
def greet(name:, shout: 'false')
|
|
20
20
|
message = "Hello, #{name}"
|
|
21
|
-
{ message: shout ==
|
|
21
|
+
{ message: shout == 'true' ? message.upcase : message }
|
|
22
22
|
end
|
|
23
23
|
end
|
|
24
24
|
|
|
@@ -59,7 +59,7 @@ The rest of this README is reference. If you only read one section, read [Types]
|
|
|
59
59
|
|
|
60
60
|
```ruby
|
|
61
61
|
# Gemfile
|
|
62
|
-
gem
|
|
62
|
+
gem 'skyward-api'
|
|
63
63
|
```
|
|
64
64
|
|
|
65
65
|
Skyward API supports every Ruby that isn't end-of-life (3.3 and later, as of November 2026), and runs on any Rack 3 server. It recommends [Falcon](https://github.com/socketry/falcon) or Puma. `skyward serve` runs Falcon, so add `gem "falcon"` to use it.
|
|
@@ -72,15 +72,15 @@ An endpoint is a public method. The class lists its routes at the top, and each
|
|
|
72
72
|
|
|
73
73
|
```ruby
|
|
74
74
|
class TodosAPI < Skyward::API
|
|
75
|
-
get
|
|
76
|
-
get
|
|
75
|
+
get '/', to: :index, summary: 'List todos, newest first.'
|
|
76
|
+
get '/:id', to: :show, summary: 'Fetch a single todo.'
|
|
77
77
|
|
|
78
78
|
def initialize(todos:)
|
|
79
79
|
super()
|
|
80
80
|
@todos = todos
|
|
81
81
|
end
|
|
82
82
|
|
|
83
|
-
def index(done: nil, limit:
|
|
83
|
+
def index(done: nil, limit: '50')
|
|
84
84
|
@todos.list(done:, limit: Integer(limit))
|
|
85
85
|
end
|
|
86
86
|
|
|
@@ -116,12 +116,12 @@ Ruby already has syntax for required and optional, so Skyward API uses it. A key
|
|
|
116
116
|
Without types, path and query values arrive as `String`s and `body:` arrives as a `Hash` with symbol keys. That makes it a good fit for pattern matching:
|
|
117
117
|
|
|
118
118
|
```ruby
|
|
119
|
-
post
|
|
119
|
+
post '/', to: :create
|
|
120
120
|
|
|
121
121
|
def create(body:)
|
|
122
122
|
case body
|
|
123
123
|
in { title: String => title } then created @todos.create(title:)
|
|
124
|
-
else unprocessable
|
|
124
|
+
else unprocessable 'title is required'
|
|
125
125
|
end
|
|
126
126
|
end
|
|
127
127
|
```
|
|
@@ -151,7 +151,7 @@ Return a value and Skyward API turns it into a response. There's no `render`, no
|
|
|
151
151
|
Every helper takes `headers:`:
|
|
152
152
|
|
|
153
153
|
```ruby
|
|
154
|
-
created todo, headers: {
|
|
154
|
+
created todo, headers: { 'location' => "/todos/#{todo.id}" }
|
|
155
155
|
```
|
|
156
156
|
|
|
157
157
|
Error responses use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json`:
|
|
@@ -172,7 +172,7 @@ Return a Rack triple for anything a value can't express: streaming, files, or a
|
|
|
172
172
|
# @rbs return: rack | Responses::NotFound
|
|
173
173
|
def export(id:)
|
|
174
174
|
todo = @todos.find(id)
|
|
175
|
-
todo ? [200, {
|
|
175
|
+
todo ? [200, { 'content-type' => 'text/csv' }, [todo.to_csv]] : not_found
|
|
176
176
|
end
|
|
177
177
|
```
|
|
178
178
|
|
|
@@ -214,16 +214,16 @@ NewTodo = Data.define(
|
|
|
214
214
|
)
|
|
215
215
|
|
|
216
216
|
class TodosAPI < Skyward::API
|
|
217
|
-
description
|
|
217
|
+
description 'Things to do, and the satisfaction of ticking them off.'
|
|
218
218
|
|
|
219
|
-
get
|
|
220
|
-
get
|
|
221
|
-
post
|
|
222
|
-
post
|
|
219
|
+
get '/', to: :index, summary: 'List todos, newest first.'
|
|
220
|
+
get '/:id', to: :show, summary: 'Fetch a single todo.'
|
|
221
|
+
post '/', to: :create, summary: 'Create a todo.'
|
|
222
|
+
post '/:id/complete', to: :complete, summary: 'Mark a todo as done.', description: <<~TEXT
|
|
223
223
|
Marking a todo that's already done is fine: it stays done, and the
|
|
224
224
|
response is the same.
|
|
225
225
|
TEXT
|
|
226
|
-
delete
|
|
226
|
+
delete '/:id', to: :destroy, summary: 'Delete a todo.'
|
|
227
227
|
|
|
228
228
|
# @rbs @todos: TodoStore
|
|
229
229
|
|
|
@@ -337,16 +337,16 @@ Documentation is plain Ruby values, written where the thing it describes is decl
|
|
|
337
337
|
```ruby
|
|
338
338
|
App = Skyward.app(
|
|
339
339
|
docs: true,
|
|
340
|
-
title:
|
|
341
|
-
version:
|
|
342
|
-
description:
|
|
340
|
+
title: 'Best Todos Ever',
|
|
341
|
+
version: '1.0.0',
|
|
342
|
+
description: 'Lists of things to do, and the todos on them.'
|
|
343
343
|
) { ... }
|
|
344
344
|
|
|
345
345
|
class TodosAPI < Skyward::API
|
|
346
|
-
description
|
|
346
|
+
description 'Things to do, and the satisfaction of ticking them off.'
|
|
347
347
|
|
|
348
|
-
get
|
|
349
|
-
post
|
|
348
|
+
get '/', to: :index, summary: 'List todos, newest first.'
|
|
349
|
+
post '/:id/complete', to: :complete, summary: 'Mark a todo as done.', description: <<~TEXT
|
|
350
350
|
Marking a todo that's already done is fine: it stays done, and the
|
|
351
351
|
response is the same.
|
|
352
352
|
TEXT
|
|
@@ -385,7 +385,7 @@ A client generated from the document takes its names from it, so every name is o
|
|
|
385
385
|
To name a schema yourself, pass `schema_names:`. It needs no change to the class, so it works for Skyward ORM records and other gems' classes too:
|
|
386
386
|
|
|
387
387
|
```ruby
|
|
388
|
-
Skyward.app(docs: true, schema_names: { Statuses::Record =>
|
|
388
|
+
Skyward.app(docs: true, schema_names: { Statuses::Record => 'Status' }) { ... }
|
|
389
389
|
```
|
|
390
390
|
|
|
391
391
|
A schema name has only letters, digits, `.`, `-` and `_`, as OpenAPI requires, and no two schemas share one, including `Problem`. Skyward API refuses to boot otherwise.
|
|
@@ -400,8 +400,8 @@ By default the page loads Scalar from the jsDelivr CDN at a pinned version, with
|
|
|
400
400
|
|
|
401
401
|
```ruby
|
|
402
402
|
# public/scalar.js is dist/browser/standalone.js from the @scalar/api-reference package.
|
|
403
|
-
Skyward.app(docs: true, scalar_url:
|
|
404
|
-
app.static
|
|
403
|
+
Skyward.app(docs: true, scalar_url: '/scalar.js') do |app|
|
|
404
|
+
app.static '/', from: 'public'
|
|
405
405
|
# ...
|
|
406
406
|
end
|
|
407
407
|
```
|
|
@@ -416,22 +416,22 @@ A URL you pass gets no integrity hash, because Skyward API can't know it. A rela
|
|
|
416
416
|
|
|
417
417
|
```ruby
|
|
418
418
|
# app.rb
|
|
419
|
-
require
|
|
420
|
-
require_relative
|
|
419
|
+
require 'skyward/api'
|
|
420
|
+
require_relative 'todos_api'
|
|
421
421
|
|
|
422
422
|
App = Skyward.app(docs: true) do |app|
|
|
423
423
|
todos = TodoStore.new(database: DB)
|
|
424
424
|
|
|
425
425
|
app.use Rack::Deflater
|
|
426
|
-
app.static
|
|
426
|
+
app.static '/', from: 'public'
|
|
427
427
|
|
|
428
|
-
app.mount TodosAPI.new(todos:), at:
|
|
428
|
+
app.mount TodosAPI.new(todos:), at: '/todos'
|
|
429
429
|
end
|
|
430
430
|
```
|
|
431
431
|
|
|
432
432
|
```ruby
|
|
433
433
|
# config.ru
|
|
434
|
-
require_relative
|
|
434
|
+
require_relative 'app'
|
|
435
435
|
run App
|
|
436
436
|
```
|
|
437
437
|
|
|
@@ -445,8 +445,8 @@ Skyward API doesn't build CORS, compression or sessions, because Rack already ha
|
|
|
445
445
|
```ruby
|
|
446
446
|
app.use Rack::Cors do
|
|
447
447
|
allow do
|
|
448
|
-
origins
|
|
449
|
-
resource
|
|
448
|
+
origins 'https://todos.example'
|
|
449
|
+
resource '*', headers: :any, methods: %i[get post delete]
|
|
450
450
|
end
|
|
451
451
|
end
|
|
452
452
|
```
|
|
@@ -472,19 +472,19 @@ class CurrentUser
|
|
|
472
472
|
# @rbs request: Request
|
|
473
473
|
# @rbs return: User | Responses::Unauthorized
|
|
474
474
|
def call(request)
|
|
475
|
-
@sessions.user_for(request.cookies[
|
|
475
|
+
@sessions.user_for(request.cookies['session']) || Skyward.unauthorized('Sign in first')
|
|
476
476
|
end
|
|
477
477
|
|
|
478
478
|
end
|
|
479
479
|
|
|
480
480
|
App = Skyward.app do |app|
|
|
481
481
|
app.provide :current_user, CurrentUser.new(sessions: Sessions.new)
|
|
482
|
-
app.mount TodosAPI.new(todos:), at:
|
|
482
|
+
app.mount TodosAPI.new(todos:), at: '/todos'
|
|
483
483
|
end
|
|
484
484
|
```
|
|
485
485
|
|
|
486
486
|
```ruby
|
|
487
|
-
get
|
|
487
|
+
get '/', to: :index
|
|
488
488
|
|
|
489
489
|
# @rbs current_user: User
|
|
490
490
|
# @rbs return: Array[Todo]
|
|
@@ -509,7 +509,7 @@ Skyward::Core::BootError: TodosAPI#show (GET /todos/:id)
|
|
|
509
509
|
The route has a path parameter :id, but the method has no `id:` keyword. Add `id:` to the method, or rename the path parameter.
|
|
510
510
|
|
|
511
511
|
app/todos_api.rb:12
|
|
512
|
-
get
|
|
512
|
+
get '/:id', to: :show
|
|
513
513
|
...
|
|
514
514
|
def show(todo_id:)
|
|
515
515
|
^^^^^^^^
|
|
@@ -532,10 +532,10 @@ When your code raises at runtime, Skyward API responds with a 500 problem+json t
|
|
|
532
532
|
To send exceptions to Sentry or a similar service, pass `on_error:`. It's called once per exception, after it's logged, with the exception and the Rack env, and takes anything that responds to `call(exception, env)`:
|
|
533
533
|
|
|
534
534
|
```ruby
|
|
535
|
-
report = ->(exception, env) { Sentry.capture_exception(exception, tags: { request_id: env[
|
|
535
|
+
report = ->(exception, env) { Sentry.capture_exception(exception, tags: { request_id: env['skyward.request_id'] }) }
|
|
536
536
|
|
|
537
537
|
App = Skyward.app(on_error: report) do |app|
|
|
538
|
-
app.mount TodosAPI.new(todos:), at:
|
|
538
|
+
app.mount TodosAPI.new(todos:), at: '/todos'
|
|
539
539
|
end
|
|
540
540
|
```
|
|
541
541
|
|
|
@@ -564,14 +564,14 @@ There's no server or Rack in that test. The fake goes in through `initialize`.
|
|
|
564
564
|
When you want the whole stack, including routing, coercion, providers and middleware, use the test client:
|
|
565
565
|
|
|
566
566
|
```ruby
|
|
567
|
-
describe
|
|
567
|
+
describe 'POST /todos' do
|
|
568
568
|
let(:client) { Skyward::API::Test.client(App) }
|
|
569
569
|
|
|
570
570
|
it "rejects a priority that doesn't exist" do
|
|
571
|
-
response = client.post
|
|
571
|
+
response = client.post '/todos', json: { title: 'Ship it', priority: 'urgent' }
|
|
572
572
|
|
|
573
573
|
assert_equal 422, response.status
|
|
574
|
-
assert_equal
|
|
574
|
+
assert_equal 'body.priority', response.json[:errors].first[:at]
|
|
575
575
|
end
|
|
576
576
|
end
|
|
577
577
|
```
|
|
@@ -621,7 +621,7 @@ DELETE /todos/:id TodosAPI#destroy (id: Integer) -> (Responses::NoC
|
|
|
621
621
|
The executable comes with Skyward Core, which every Skyward gem depends on. It finds each gem's `lib/skyward/<gem>/commands.rb` with `Gem.find_files` and loads it, and that file registers the gem's commands:
|
|
622
622
|
|
|
623
623
|
```ruby
|
|
624
|
-
Skyward::Core::CLI.register(
|
|
624
|
+
Skyward::Core::CLI.register('routes', 'List every route and the method that serves it') do |args|
|
|
625
625
|
# ...
|
|
626
626
|
end
|
|
627
627
|
```
|
|
@@ -630,7 +630,7 @@ Skyward API's commands run in your app's directory. `skyward serve` runs `config
|
|
|
630
630
|
|
|
631
631
|
### `skyward check` in CI
|
|
632
632
|
|
|
633
|
-
Run `skyward check` as a required CI step in every Skyward app. Skyward API reads signatures at boot, and `rbs` stays one of its runtime dependencies
|
|
633
|
+
Run `skyward check` as a required CI step in every Skyward app. Skyward API reads the signatures you deployed at every boot, and `rbs` stays one of its runtime dependencies in 1.0, as [Skyward Core](../skyward-core/README.md#what-it-owns) explains, so a deploy with stale signatures quietly validates requests against the old contract. `check` is what catches it. It checks three things, in order, and checks all three even after one fails, then exits 1 if any failed:
|
|
634
634
|
|
|
635
635
|
1. **Signatures.** It runs rbs-inline over the app's Ruby, outside `test/`, `spec/`, `vendor/`, `tmp/` and hidden directories, and fails if the result differs from `sig/generated`, listing the files that differ and the command that regenerates them.
|
|
636
636
|
2. **Strict boot.** It loads `app.rb` with `SKYWARD_STRICT=1`, so an untyped endpoint, or any other boot error, fails it.
|
|
@@ -641,8 +641,8 @@ It needs rbs-inline and Steep in the app's bundle, and a `Steepfile`:
|
|
|
641
641
|
```ruby
|
|
642
642
|
# Gemfile
|
|
643
643
|
group :development, :test do
|
|
644
|
-
gem
|
|
645
|
-
gem
|
|
644
|
+
gem 'rbs-inline', require: false
|
|
645
|
+
gem 'steep', require: false
|
|
646
646
|
end
|
|
647
647
|
```
|
|
648
648
|
|
|
@@ -683,7 +683,7 @@ No type error detected.
|
|
|
683
683
|
This README is the spec, and this section lists each part of it that's built, as it lands. Anything it describes that isn't listed here isn't built yet.
|
|
684
684
|
|
|
685
685
|
- **Route declarations.** An API class subclasses `Skyward::API` and lists its routes with `get`, `post`, `put`, `patch` and `delete`, each with an optional `summary:` and `description:`, and describes itself with `description`. A subclass starts with its parent's routes. A path that doesn't start with `/`, a path parameter that isn't a valid keyword name or appears twice, or a `to:` that isn't a Symbol raises `ArgumentError` where it's declared. The rest is checked at boot, below.
|
|
686
|
-
- **Building an app.** `Skyward.app` yields a builder and returns a frozen Rack app, and the builder is frozen once the block returns. `mount` attaches an API object at a prefix (`at:`, `/` by default), and raises `Skyward::Core::BootError` given anything but a `Skyward::API` instance. One object can be mounted at several prefixes. A request matches a route when its method and whole path match, trailing slash included, with each path parameter matching one non-empty segment, percent-decoded. Routes are
|
|
686
|
+
- **Building an app.** `Skyward.app` yields a builder and returns a frozen Rack app, and the builder is frozen once the block returns. `mount` attaches an API object at a prefix (`at:`, `/` by default), and raises `Skyward::Core::BootError` given anything but a `Skyward::API` instance. One object can be mounted at several prefixes. A request matches a route when its method and whole path match, trailing slash included, with each path parameter matching one non-empty segment, percent-decoded. Routes are compiled into one matcher at boot, and when several routes match a request, the first in mount order, then declaration order, answers. The method is called with its inputs, below, and its return value is answered by its return type, as Responses below describes. A request whose path no route matches gets a 404 problem+json.
|
|
687
687
|
- **Checks at boot.** `Skyward.app` loads the RBS signatures under `signatures:` (`"sig"` by default, relative to the current directory) along with Skyward API's own, so an app's signatures can subclass `Skyward::API`. It refuses to boot with a `Skyward::Core::BootError` on the first problem it finds, and the message starts with the route's label, such as `TodosAPI#show (GET /todos/:id)`, then says what's wrong and how to fix it. It refuses a `summary:` with a line break; a route that an earlier one with the same verb, in any mount, matches every path of, as `/todos/:id` does `/todos/new`; a method that isn't public, or that takes positional arguments or `**rest`; a signature whose keywords differ from the method's, in name or in being required, which means it's stale; a path parameter with no keyword of its name; a path parameter whose name is provided; a `request:` keyword typed as anything but `Skyward::API::Request`; a provided keyword whose type isn't its provider's value, as Providers below describes; a type that can't be read; and a path or query keyword typed as a record, a hash, a class, or an array in a path or inside an array. Each endpoint keeps its method type as its signature file writes it, or for an untyped endpoint, below, as rbs-inline would, and its keywords, with each one's name, its source (the path for a path parameter, the body for `body:`, the request for `request:`, and otherwise the query string), whether it's required and its type, keeps the provider of each provided keyword apart from them, in keyword order, and keeps the members of its return type, reading `Skyward::API::Responses::Created[T]` with the type of its value, the other response values by their class, and `Skyward::API::rack`, or the tuple it names, as a Rack triple, and refusing a `Skyward::API::Responses::Created` without one. A class or method with no signature, including when there's no `signatures:` directory at all, is an untyped endpoint: each keyword is `untyped`, required as the method requires it, and so is its return type, which is what rbs-inline writes for a method with no annotations. `request:` may be typed `untyped` too, and is still the request. With `Skyward.app(strict: true)`, or with `SKYWARD_STRICT=1` in the environment whatever `strict:` says, once the other checks pass, boot refuses every untyped endpoint, not just the first, each starting with its label: one with no signature, or one whose signature types a keyword or a member of its return type as `untyped`, naming which. `untyped` inside a type, as in `Array[untyped]`, isn't refused, and nor is `request:`. Every line of the problem is indented two spaces, and below it a refusal shows an excerpt of the code at fault, indented four, as Skyward Core renders it, and then a hint, indented two. `get`, `post`, `put`, `patch` and `delete` record the file and line they're called from, and the route's line has carets under `summary:`'s value for a line break, under the path of both routes for a shadowed one, and under `to:`'s value for a method that isn't public. The `def` has carets under its parameters for positional arguments or `**rest`, under the keyword for a `request:`, provided, path or query keyword's type or a type that can't be read, and under its name for a return type that can't be read. A path parameter that's provided shows the route with carets under the parameter, then the `def` with carets under the keyword. A path parameter with no keyword shows the route, then the `def`, and the hint ``Did you mean `def show(id:)`?``, the `def` line's parameters with the keyword it means renamed: of the keywords the query string would carry, the closest by Ruby's `DidYouMean`, or else the only one that ends in `_<parameter>` or that the parameter ends in `_<keyword>`, as `todo_id:` for `/:id`. The carets go under that keyword, or under the parameters when none is meant, and there's a hint only when the parameter list is written whole on the `def` line. A method that isn't public gets ``index is private. Move it above `private`.`` when the class has a private or protected method of that name, or else `Did you mean to: :index?` naming the closest of the class's own public methods, and a type that can't be read gets Skyward Core's `Did you mean` for a misspelt class name. An RBS error reading the signature shows Skyward Core's excerpt of the RBS and its suggestion. A stale signature, and `strict: true`'s refusals, have no excerpt, and a route or method in a file that can't be read, as from `eval`, gets no excerpt, and no `def` hint.
|
|
688
688
|
- **Inputs.** Each endpoint's keywords are compiled into coercers at boot, and filled on each request before the method runs: a path parameter from the path, `body:` from the JSON body, `request:` with the request, below, a provided keyword from its provider, below, and any other keyword from the query string, each but `request:` and a provided keyword coerced to its type. In a path or query, `Integer` matches `-?\d+`, `Float` is parsed with `Float()` and must be finite, and `bool` takes `true`, `false`, `1` and `0`. In a body, a number or boolean must already be one, and an Integer is accepted as a Float. `Date` is `YYYY-MM-DD` and must exist, and `Time` is ISO 8601 with `T`, seconds, an optional fraction and `Z` or `±HH:MM`. `BigDecimal` takes a String of an optional `-`, digits, and an optional `.` and digits (`"12.50"`, `"-3"`, `"0.001"`), the same in a path, a query and a body, and gives `BigDecimal(raw)`. Anything else doesn't fit, an exponent, `NaN` and an empty string included, and so doesn't a JSON number, which is parsed as a `Float` and may have lost digits: `expected BigDecimal (a decimal string, such as "12.50"), got 12.5`. A symbol union takes a symbol's name and gives the Symbol, and a union takes its first member that fits, in declared order. `Array[T]` in a query comes from repeated keys, one value is a one-item array, and `tag[]` is a different key; an `untyped` keyword takes the last value of a key given more than once, and any other keyword given more than once doesn't fit. A record becomes a Hash with Symbol keys, and a class with typed readers is built with `new(**fields)`, both ignoring undeclared keys. `Hash[String, T]` takes a JSON object, empty or not, and coerces each value by `T`, keeping its key a String. An `untyped` path or query value is its String. Each value of a `Hash[String, untyped]` or `Hash[String, untyped?]` is the JSON as it's parsed, with String keys at every level. Any other `untyped` part of a body, such as an untyped endpoint's `body:`, an `untyped` field or an item of `Array[untyped]`, is the JSON as it's parsed, with Symbol keys at every level. An empty query value is a value, so `?limit=` doesn't fit `Integer`. A missing required keyword or field is `nil` when it's nullable, and otherwise `is required`. An absent optional keyword isn't passed, so Ruby's default applies, and an absent optional record field is left out. A request that doesn't fit answers a 422 problem+json titled `Unprocessable Content`, whose `errors` list every problem, up to the first 1,000, after which coercion stops, each with where it is (`path.id`, `query.limit`, `body.priority`, `body.tags[1]`, `body.scores["alice"]`, with a hash's key JSON-quoted so a dot or bracket in it is unambiguous, and a key longer than 200 characters cut to 200, ending `…`) and a message, such as `expected :low | :normal | :high, got "urgent"`, whose expected type, when longer than 200 characters, is cut to 200, ending `…`. A query string with unescaped bytes outside ASCII is a 422 at `query`, and a body that isn't JSON, or isn't UTF-8, is a 422 at `body`. The body is read only for an endpoint with `body:`, as [Production](#production) describes, and a missing or empty one is absent.
|
|
689
689
|
- **The request.** An endpoint that takes `request:` is passed a frozen `Skyward::API::Request`, built from the Rack env once on each request, only for an endpoint that takes it or a provided keyword, and passed even when the keyword has a default. It wraps the env rather than subclassing `Rack::Request`, because Skyward API doesn't depend on Rack. `headers` is a frozen Hash of every `HTTP_` variable in the env, named in lowercase with dashes (`request.headers["authorization"]`), along with `content-type` and `content-length`. `cookies` is a frozen Hash read from the `cookie` header, each value percent-decoded with a `+` left as it is, and the first of two cookies with one name wins. `ip` is the client's address as Rack finds it: the remote address, unless it's a trusted proxy (a loopback or private address, `localhost` or a Unix socket), and otherwise the last `X-Forwarded-For` address that isn't one, or the first when every one is, or the remote address when there's no `X-Forwarded-For`, or `nil` with neither. The `Forwarded` header isn't read. `request_id` is the request's ID, and `env` is the env itself.
|
|
@@ -7,14 +7,14 @@ module Skyward::API::Assembly::Boot
|
|
|
7
7
|
|
|
8
8
|
KEYWORD = %i[keyreq key].freeze #: Array[Symbol]
|
|
9
9
|
|
|
10
|
-
RACK = [
|
|
10
|
+
RACK = ['::Skyward::API::rack', '[::Integer, ::Hash[::String, ::String], untyped]'].map do |type|
|
|
11
11
|
RBS::Parser.parse_type(type)
|
|
12
12
|
end.freeze #: Array[RBS::Types::t?]
|
|
13
13
|
|
|
14
|
-
REQUEST = RBS::Parser.parse_type(
|
|
14
|
+
REQUEST = RBS::Parser.parse_type('::Skyward::API::Request') #: RBS::Types::t?
|
|
15
15
|
|
|
16
16
|
REQUEST_TYPE = Skyward::Core::Types::Named.new(
|
|
17
|
-
name:
|
|
17
|
+
name: 'Skyward::API::Request',
|
|
18
18
|
klass: Skyward::API::Request,
|
|
19
19
|
fields: []
|
|
20
20
|
) #: Skyward::Core::Types::Named
|
|
@@ -151,7 +151,7 @@ module Skyward::API::Assembly::Boot
|
|
|
151
151
|
return unless route.summary&.match?(/\R/)
|
|
152
152
|
|
|
153
153
|
refused(
|
|
154
|
-
|
|
154
|
+
'Its summary: has a line break, but a summary is one line. Put the rest in description:.',
|
|
155
155
|
spots: [argument(route, :summary)]
|
|
156
156
|
)
|
|
157
157
|
end
|
|
@@ -160,14 +160,14 @@ module Skyward::API::Assembly::Boot
|
|
|
160
160
|
# @rbs path: String
|
|
161
161
|
# @rbs return: String
|
|
162
162
|
def full_path(prefix, path)
|
|
163
|
-
parts = [prefix, path].map { |part| part.delete_prefix(
|
|
164
|
-
"/#{parts.reject(&:empty?).join(
|
|
163
|
+
parts = [prefix, path].map { |part| part.delete_prefix('/').delete_suffix('/') }
|
|
164
|
+
"/#{parts.reject(&:empty?).join('/')}"
|
|
165
165
|
end
|
|
166
166
|
|
|
167
167
|
# @rbs path: String
|
|
168
168
|
# @rbs return: Array[String | Symbol]
|
|
169
169
|
def pattern(path)
|
|
170
|
-
path.split(
|
|
170
|
+
path.split('/', -1).map { |segment| segment.start_with?(':') ? segment.delete_prefix(':').to_sym : segment }
|
|
171
171
|
end
|
|
172
172
|
|
|
173
173
|
# @rbs route: Skyward::API::Endpoints::Route
|
|
@@ -183,10 +183,10 @@ module Skyward::API::Assembly::Boot
|
|
|
183
183
|
problem =
|
|
184
184
|
if covers?(pattern, earlier.pattern)
|
|
185
185
|
"#{earlier.label} is tried first and matches exactly the same paths, so this route is never reached. " \
|
|
186
|
-
|
|
186
|
+
'Remove one of them, or change a path.'
|
|
187
187
|
else
|
|
188
188
|
"#{earlier.label} is tried first and matches every path this route does, so this route is never reached. " \
|
|
189
|
-
|
|
189
|
+
'Declare the static route first.'
|
|
190
190
|
end
|
|
191
191
|
refused(problem, spots: [earlier_route, route].map { |declared| in_path(declared, declared.path) })
|
|
192
192
|
end
|
|
@@ -197,7 +197,7 @@ module Skyward::API::Assembly::Boot
|
|
|
197
197
|
# @rbs return: bool
|
|
198
198
|
def covers?(pattern, other)
|
|
199
199
|
pattern.length == other.length &&
|
|
200
|
-
pattern.zip(other).all? { |part, other_part| part == other_part || (part.is_a?(Symbol) && other_part !=
|
|
200
|
+
pattern.zip(other).all? { |part, other_part| part == other_part || (part.is_a?(Symbol) && other_part != '') }
|
|
201
201
|
end
|
|
202
202
|
|
|
203
203
|
# @rbs api: Skyward::API
|
|
@@ -228,7 +228,7 @@ module Skyward::API::Assembly::Boot
|
|
|
228
228
|
both = path_parameters.find { |name| providers.key?(name) }
|
|
229
229
|
if both
|
|
230
230
|
problem = "The route has a path parameter :#{both}, but :#{both} is provided too, so `#{both}:` can't be both. " \
|
|
231
|
-
|
|
231
|
+
'Rename the path parameter, or provide another name.'
|
|
232
232
|
return refused(
|
|
233
233
|
problem,
|
|
234
234
|
spots: [in_path(route, ":#{both}"), Skyward::Core::Diagnostics::Spots.keyword_parameter(method, both)]
|
|
@@ -294,8 +294,8 @@ module Skyward::API::Assembly::Boot
|
|
|
294
294
|
# @rbs return: String?
|
|
295
295
|
def unrouted(klass, to)
|
|
296
296
|
hidden =
|
|
297
|
-
if klass.private_method_defined?(to, false) then
|
|
298
|
-
elsif klass.protected_method_defined?(to, false) then
|
|
297
|
+
if klass.private_method_defined?(to, false) then 'private'
|
|
298
|
+
elsif klass.protected_method_defined?(to, false) then 'protected'
|
|
299
299
|
end
|
|
300
300
|
return "#{to} is #{hidden}. Move it above `#{hidden}`." if hidden
|
|
301
301
|
|
|
@@ -319,8 +319,8 @@ module Skyward::API::Assembly::Boot
|
|
|
319
319
|
parameters = method.parameters
|
|
320
320
|
if parameters.any? { |kind, _| UNNAMED.include?(kind) }
|
|
321
321
|
return refused(
|
|
322
|
-
|
|
323
|
-
|
|
322
|
+
'The method takes positional arguments or **rest, but Skyward API passes only named keywords. ' \
|
|
323
|
+
'Take each input as a keyword, such as `id:`.',
|
|
324
324
|
spots: [Skyward::Core::Diagnostics::Spots.parameters(method)]
|
|
325
325
|
)
|
|
326
326
|
end
|
|
@@ -355,10 +355,10 @@ module Skyward::API::Assembly::Boot
|
|
|
355
355
|
# @rbs function: RBS::Types::function
|
|
356
356
|
# @rbs return: Refusal
|
|
357
357
|
def stale(keywords, function)
|
|
358
|
-
taken = keywords.map { |name, required| "#{
|
|
358
|
+
taken = keywords.map { |name, required| "#{'?' unless required}#{name}:" }
|
|
359
359
|
refused(
|
|
360
|
-
"The method takes (#{taken.join(
|
|
361
|
-
|
|
360
|
+
"The method takes (#{taken.join(', ')}), but its signature takes (#{written(function.param_to_s)}), " \
|
|
361
|
+
'so the signature is stale. Run rbs-inline, or update the signature.'
|
|
362
362
|
)
|
|
363
363
|
end
|
|
364
364
|
|
|
@@ -425,7 +425,7 @@ module Skyward::API::Assembly::Boot
|
|
|
425
425
|
columns = keyword.columns
|
|
426
426
|
text = parameters.text
|
|
427
427
|
line = method.source_location&.last
|
|
428
|
-
return unless list && columns && parameters.line == line && text[list.end] ==
|
|
428
|
+
return unless list && columns && parameters.line == line && text[list.end] == ')' && keyword.line == line
|
|
429
429
|
|
|
430
430
|
renamed = text[columns].to_s.sub(/\A[^:]+/, parameter.to_s)
|
|
431
431
|
rewritten = "#{text[list.begin...columns.begin]}#{renamed}#{text[columns.end...list.end]}"
|
|
@@ -471,7 +471,7 @@ module Skyward::API::Assembly::Boot
|
|
|
471
471
|
def request(required, type)
|
|
472
472
|
unless [REQUEST, ANY].include?(type)
|
|
473
473
|
return refused(
|
|
474
|
-
|
|
474
|
+
'`request:` is always the Skyward::API::Request, but its signature types it as ' \
|
|
475
475
|
"#{written(type.to_s)}. Type it as Skyward::API::Request, or rename the keyword."
|
|
476
476
|
)
|
|
477
477
|
end
|
|
@@ -489,10 +489,10 @@ module Skyward::API::Assembly::Boot
|
|
|
489
489
|
value = provider.value
|
|
490
490
|
return provider if value.nil? || untyped_type?(type) || same?(parts(type), value)
|
|
491
491
|
|
|
492
|
-
returned = value.empty? ?
|
|
492
|
+
returned = value.empty? ? 'only responses' : "#{written(value.join(' | '))}, besides any responses"
|
|
493
493
|
refused(
|
|
494
494
|
"`#{name}:` is typed as #{written(type.to_s)}, but the :#{name} provider returns #{returned}. " \
|
|
495
|
-
|
|
495
|
+
'Give them the same type.'
|
|
496
496
|
)
|
|
497
497
|
end
|
|
498
498
|
|
|
@@ -517,7 +517,7 @@ module Skyward::API::Assembly::Boot
|
|
|
517
517
|
if uncarried
|
|
518
518
|
refused(
|
|
519
519
|
"`#{name}:` comes from the path, which can't carry #{uncarried}. " \
|
|
520
|
-
|
|
520
|
+
'Give it a type such as String, Integer or an enum.'
|
|
521
521
|
)
|
|
522
522
|
end
|
|
523
523
|
when :query
|
|
@@ -525,7 +525,7 @@ module Skyward::API::Assembly::Boot
|
|
|
525
525
|
if uncarried
|
|
526
526
|
refused(
|
|
527
527
|
"`#{name}:` comes from the query string, which can't carry #{uncarried}. " \
|
|
528
|
-
|
|
528
|
+
'Give it a type such as String, Integer or an array of them, or take it in `body:`.'
|
|
529
529
|
)
|
|
530
530
|
end
|
|
531
531
|
end
|
|
@@ -536,14 +536,14 @@ module Skyward::API::Assembly::Boot
|
|
|
536
536
|
# @rbs return: String?
|
|
537
537
|
def uncarried(type, within)
|
|
538
538
|
case type
|
|
539
|
-
when Skyward::Core::Types::Record then
|
|
540
|
-
when Skyward::Core::Types::HashOf then
|
|
539
|
+
when Skyward::Core::Types::Record then 'a record'
|
|
540
|
+
when Skyward::Core::Types::HashOf then 'a hash'
|
|
541
541
|
when Skyward::Core::Types::Named then "#{type.name}, a class"
|
|
542
542
|
when Skyward::Core::Types::ArrayOf
|
|
543
543
|
case within
|
|
544
|
-
when :path then
|
|
544
|
+
when :path then 'an array'
|
|
545
545
|
when :query then uncarried(type.type, :array)
|
|
546
|
-
else
|
|
546
|
+
else 'an array of arrays'
|
|
547
547
|
end
|
|
548
548
|
when Skyward::Core::Types::Nullable then uncarried(type.type, within)
|
|
549
549
|
when Skyward::Core::Types::Union then type.types.lazy.filter_map { |member| uncarried(member, within) }.first
|
|
@@ -557,7 +557,7 @@ module Skyward::API::Assembly::Boot
|
|
|
557
557
|
def returns(type, reader)
|
|
558
558
|
read = parts(type).map { |part| response(part, reader) || reader.read(part) }
|
|
559
559
|
unreadable = read.find { |member| member.is_a?(Skyward::Core::Types::Unreadable) }
|
|
560
|
-
return unreadable(
|
|
560
|
+
return unreadable('The return type', unreadable) if unreadable.is_a?(Skyward::Core::Types::Unreadable)
|
|
561
561
|
|
|
562
562
|
readable = read.grep_v(Skyward::Core::Types::Unreadable) #: Array[Skyward::API::Routing::Router::returned]
|
|
563
563
|
readable.flat_map { |member| members(member) }.uniq
|
|
@@ -579,7 +579,7 @@ module Skyward::API::Assembly::Boot
|
|
|
579
579
|
# | Skyward::Core::Types::Unreadable | nil
|
|
580
580
|
def response(type, reader)
|
|
581
581
|
return Skyward::API::Routing::Router::Rack.new if RACK.include?(type)
|
|
582
|
-
if type.is_a?(RBS::Types::ClassInstance) && type.name.to_s ==
|
|
582
|
+
if type.is_a?(RBS::Types::ClassInstance) && type.name.to_s == '::Skyward::API::Responses::Created'
|
|
583
583
|
return created(type, reader)
|
|
584
584
|
end
|
|
585
585
|
|
|
@@ -600,7 +600,7 @@ module Skyward::API::Assembly::Boot
|
|
|
600
600
|
# @rbs return: Skyward::API::Routing::Router::Created | Skyward::Core::Types::Unreadable
|
|
601
601
|
def created(type, reader)
|
|
602
602
|
unless type.args.size == 1
|
|
603
|
-
instead =
|
|
603
|
+
instead = 'Skyward::API::Responses::Created[T]'
|
|
604
604
|
return Skyward::Core::Types::Unreadable.new(type: written(type.to_s), at: nil, instead:, suggestion: nil)
|
|
605
605
|
end
|
|
606
606
|
|
|
@@ -631,8 +631,8 @@ module Skyward::API::Assembly::Boot
|
|
|
631
631
|
if function
|
|
632
632
|
untyped_parts(endpoint, function)
|
|
633
633
|
else
|
|
634
|
-
|
|
635
|
-
|
|
634
|
+
'It has no RBS signature, but strict: true refuses an untyped endpoint. ' \
|
|
635
|
+
'Annotate it and run rbs-inline, or check `signatures:`.'
|
|
636
636
|
end
|
|
637
637
|
"#{endpoint.label}\n #{problem}" if problem
|
|
638
638
|
end
|
|
@@ -654,13 +654,13 @@ module Skyward::API::Assembly::Boot
|
|
|
654
654
|
"`#{provider.name}:`" if untyped_type?(params.fetch(provider.name).type)
|
|
655
655
|
end
|
|
656
656
|
named = [*keywords, *provided]
|
|
657
|
-
found = endpoint.returns.include?(any) ? [*named,
|
|
657
|
+
found = endpoint.returns.include?(any) ? [*named, 'the return type'] : named
|
|
658
658
|
return if found.empty?
|
|
659
659
|
|
|
660
660
|
*rest, last = found
|
|
661
|
-
listed = rest.empty? ? last : "#{rest.join(
|
|
661
|
+
listed = rest.empty? ? last : "#{rest.join(', ')} and #{last}"
|
|
662
662
|
"Its signature leaves #{listed} untyped, but strict: true refuses an untyped endpoint. " \
|
|
663
|
-
"Give #{found.one? ?
|
|
663
|
+
"Give #{found.one? ? 'it' : 'each'} a type."
|
|
664
664
|
end
|
|
665
665
|
|
|
666
666
|
# @rbs subject: String
|
|
@@ -677,5 +677,5 @@ module Skyward::API::Assembly::Boot
|
|
|
677
677
|
|
|
678
678
|
# @rbs text: String
|
|
679
679
|
# @rbs return: String
|
|
680
|
-
def written(text) = text.gsub(/(?<!\w)::/,
|
|
680
|
+
def written(text) = text.gsub(/(?<!\w)::/, '')
|
|
681
681
|
end
|
|
@@ -41,7 +41,7 @@ class Skyward::API::Assembly::Builder
|
|
|
41
41
|
# @rbs api: Skyward::API
|
|
42
42
|
# @rbs at: String
|
|
43
43
|
# @rbs return: void
|
|
44
|
-
def mount(api, at:
|
|
44
|
+
def mount(api, at: '/')
|
|
45
45
|
# Steep proves a typed caller passes an API, but an untyped one can pass anything.
|
|
46
46
|
unless api.is_a?(Skyward::API) # steep:ignore UnreachableBranch
|
|
47
47
|
raise Skyward::Core::BootError, "mount takes a Skyward::API instance, got #{api.inspect}"
|
|
@@ -72,7 +72,7 @@ class Skyward::API::Assembly::Builder
|
|
|
72
72
|
if %i[body request].include?(name)
|
|
73
73
|
raise Skyward::Core::BootError,
|
|
74
74
|
"provide #{name.inspect}: Skyward API fills `#{name}:` itself, so it can't be provided. " \
|
|
75
|
-
|
|
75
|
+
'Provide another name.'
|
|
76
76
|
end
|
|
77
77
|
if @providers.key?(name)
|
|
78
78
|
raise Skyward::Core::BootError, "provide #{name.inspect}: it's already provided. Provide each name once."
|