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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e72e644d6adbeff511700cdcc2197311da17c48b90100c21842aad90da0ab109
4
- data.tar.gz: 5b39f4e0d513aeca35ded649fddaf796aa5026a563d84649b692d9d3d6079003
3
+ metadata.gz: ae83d4087ae6b30e2f71d46ccbe2411aa9b0eda9fb9e808668729ccd26285dc6
4
+ data.tar.gz: b0931995b0908395f024d9aafcfe52c361c722cc37c92374c76ed697a9f9108c
5
5
  SHA512:
6
- metadata.gz: e22a5084b19c1dfbbc09a2b544123d916697db91df7aca9d6a8b8d77a5dc25ee36a7b94468ae24b06d4bdf2b63061d3effab0c4c1b9377044b397216045f0218
7
- data.tar.gz: d3658ebfe3ecddc6a091af040ae41c324711349961695192074da79d30dad57d411b2a5bcbd3a5e75d36d582cab75ebacb9620db33243cba94f90ce2dd838e42
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 "skyward/api"
14
+ require 'skyward/api'
15
15
 
16
16
  class Hello < Skyward::API
17
- get "/hello/:name", to: :greet
17
+ get '/hello/:name', to: :greet
18
18
 
19
- def greet(name:, shout: "false")
19
+ def greet(name:, shout: 'false')
20
20
  message = "Hello, #{name}"
21
- { message: shout == "true" ? message.upcase : message }
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 "skyward-api"
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 "/", to: :index, summary: "List todos, newest first."
76
- get "/:id", to: :show, summary: "Fetch a single todo."
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: "50")
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 "/", to: :create
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 "title is required"
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: { "location" => "/todos/#{todo.id}" }
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, { "content-type" => "text/csv" }, [todo.to_csv]] : not_found
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 "Things to do, and the satisfaction of ticking them off."
217
+ description 'Things to do, and the satisfaction of ticking them off.'
218
218
 
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
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 "/:id", to: :destroy, summary: "Delete a todo."
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: "Best Todos Ever",
341
- version: "1.0.0",
342
- description: "Lists of things to do, and the todos on them."
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 "Things to do, and the satisfaction of ticking them off."
346
+ description 'Things to do, and the satisfaction of ticking them off.'
347
347
 
348
- get "/", to: :index, summary: "List todos, newest first."
349
- post "/:id/complete", to: :complete, summary: "Mark a todo as done.", description: <<~TEXT
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 => "Status" }) { ... }
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: "/scalar.js") do |app|
404
- app.static "/", from: "public"
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 "skyward/api"
420
- require_relative "todos_api"
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 "/", from: "public"
426
+ app.static '/', from: 'public'
427
427
 
428
- app.mount TodosAPI.new(todos:), at: "/todos"
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 "app"
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 "https://todos.example"
449
- resource "*", headers: :any, methods: %i[get post delete]
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["session"]) || Skyward.unauthorized("Sign in first")
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: "/todos"
482
+ app.mount TodosAPI.new(todos:), at: '/todos'
483
483
  end
484
484
  ```
485
485
 
486
486
  ```ruby
487
- get "/", to: :index
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 "/:id", to: :show
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["skyward.request_id"] }) }
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: "/todos"
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 "POST /todos" do
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 "/todos", json: { title: "Ship it", priority: "urgent" }
571
+ response = client.post '/todos', json: { title: 'Ship it', priority: 'urgent' }
572
572
 
573
573
  assert_equal 422, response.status
574
- assert_equal "body.priority", response.json[:errors].first[:at]
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("routes", "List every route and the method that serves it") do |args|
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 through 0.x, 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:
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 "rbs-inline", require: false
645
- gem "steep", require: false
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 tried in mount order, then declaration order. 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.
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 = ["::Skyward::API::rack", "[::Integer, ::Hash[::String, ::String], untyped]"].map do |type|
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("::Skyward::API::Request") #: RBS::Types::t?
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: "Skyward::API::Request",
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
- "Its summary: has a line break, but a summary is one line. Put the rest in description:.",
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("/").delete_suffix("/") }
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("/", -1).map { |segment| segment.start_with?(":") ? segment.delete_prefix(":").to_sym : segment }
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
- "Remove one of them, or change a path."
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
- "Declare the static route first."
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
- "Rename the path parameter, or provide another name."
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 "private"
298
- elsif klass.protected_method_defined?(to, false) then "protected"
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
- "The method takes positional arguments or **rest, but Skyward API passes only named keywords. " \
323
- "Take each input as a keyword, such as `id:`.",
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| "#{"?" unless required}#{name}:" }
358
+ taken = keywords.map { |name, required| "#{'?' unless required}#{name}:" }
359
359
  refused(
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."
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] == ")" && keyword.line == line
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
- "`request:` is always the Skyward::API::Request, but its signature types it as " \
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? ? "only responses" : "#{written(value.join(" | "))}, besides any responses"
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
- "Give them the same type."
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
- "Give it a type such as String, Integer or an enum."
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
- "Give it a type such as String, Integer or an array of them, or take it in `body:`."
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 "a record"
540
- when Skyward::Core::Types::HashOf then "a hash"
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 "an array"
544
+ when :path then 'an array'
545
545
  when :query then uncarried(type.type, :array)
546
- else "an array of arrays"
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("The return type", unreadable) if unreadable.is_a?(Skyward::Core::Types::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 == "::Skyward::API::Responses::Created"
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 = "Skyward::API::Responses::Created[T]"
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
- "It has no RBS signature, but strict: true refuses an untyped endpoint. " \
635
- "Annotate it and run rbs-inline, or check `signatures:`."
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, "the return type"] : 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(", ")} and #{last}"
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? ? "it" : "each"} a type."
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
- "Provide another name."
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."