skyward-api 0.3.0 → 0.4.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: '039ffb7a33af95928e5ce5068f752df1955cd10125e0b1db2259c1175a190109'
4
- data.tar.gz: 2f89394fd909cd45274e5cc5042037f20e548746d162ec27947cecb9bd82d220
3
+ metadata.gz: e72e644d6adbeff511700cdcc2197311da17c48b90100c21842aad90da0ab109
4
+ data.tar.gz: 5b39f4e0d513aeca35ded649fddaf796aa5026a563d84649b692d9d3d6079003
5
5
  SHA512:
6
- metadata.gz: 012d4896ea8fdacfb4177875f1a426003334b45ab94796defe98d622359cf63ed79bdb371d4529986a562dbce8cfec219a0d820e5ac5c421db1db66d881bb52d
7
- data.tar.gz: 44e096875488c41b97a7fbd5343d59176b280c195271224248a2bd7c3d6c9afac04d79ee55e25bda6b9562c5fe726c0784ff1c824c47c6c388fc8639dbe5e2a2
6
+ metadata.gz: e22a5084b19c1dfbbc09a2b544123d916697db91df7aca9d6a8b8d77a5dc25ee36a7b94468ae24b06d4bdf2b63061d3effab0c4c1b9377044b397216045f0218
7
+ data.tar.gz: d3658ebfe3ecddc6a091af040ae41c324711349961695192074da79d30dad57d411b2a5bcbd3a5e75d36d582cab75ebacb9620db33243cba94f90ce2dd838e42
data/README.md CHANGED
@@ -178,6 +178,8 @@ end
178
178
 
179
179
  Nothing checks what a triple sends, which is why it's opt-in through the return type. An `Array[T]` return is always JSON, even with three items.
180
180
 
181
+ Where the return type is `untyped`, as an untyped endpoint's is, or has an `untyped` member, as `Todo | untyped` does, nothing says a value is a triple. So it's sent as one only when it's an `Array` of exactly three items: an `Integer` from 100 to 599, a `Hash`, and a body that responds to `each` or `call`. Anything else is JSON, so `[200, {}, "hi"]` is a JSON array. An untyped endpoint can't return a three-item array that passes, such as `[200, {}, []]`, as JSON. Type its return as an `Array` for that.
182
+
181
183
  ---
182
184
 
183
185
  ## Types
@@ -274,12 +276,13 @@ end
274
276
  | `String` | string | `string` |
275
277
  | `Integer` | `42`, or `"42"` in a path or query | `integer` |
276
278
  | `Float` | number | `number` |
279
+ | `BigDecimal` | a decimal string, such as `"12.50"` | `string`, format `decimal` |
277
280
  | `bool` | `true` / `false`, or `"true"`, `"false"`, `"1"`, `"0"` in a query | `boolean` |
278
281
  | `Date`, `Time` | ISO 8601 strings | `string`, format `date` / `date-time` |
279
282
  | `T?` | absent or `null` | not required / nullable |
280
283
  | `:low \| :high` | `"low"` or `"high"`, given to you as a Symbol | `enum` |
281
284
  | `Array[T]` | array; repeated keys in a query (`?tag=a&tag=b`) | `array` |
282
- | `Hash[String, T]` | object | `object` with `additionalProperties` |
285
+ | `Hash[String, T]` | object; an `untyped` value keeps String keys at every level | `object` with `additionalProperties` |
283
286
  | `{ id: Integer }` (record) | object | inline `object` |
284
287
  | a class with typed readers | object | `object` component, referenced by `$ref` |
285
288
  | `A \| B` (such classes) | either | `oneOf` |
@@ -503,8 +506,9 @@ Skyward API checks your app at boot, so mistakes show up when you start it, not
503
506
 
504
507
  ```
505
508
  Skyward::Core::BootError: TodosAPI#show (GET /todos/:id)
506
- The route has a path parameter :id, but the method has no `id:` keyword.
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.
507
510
 
511
+ app/todos_api.rb:12
508
512
  get "/:id", to: :show
509
513
  ...
510
514
  def show(todo_id:)
@@ -512,7 +516,7 @@ Skyward::Core::BootError: TodosAPI#show (GET /todos/:id)
512
516
  Did you mean `def show(id:)`?
513
517
  ```
514
518
 
515
- Boot also catches a route that names a method the class doesn't have, a route that shadows another, an unknown type in a signature, and a keyword that matches nothing. With `strict: true`, it also catches every untyped endpoint: one that has no signature at all, or whose signature types a keyword or the return as `untyped`.
519
+ Boot also catches a route that names a method the class doesn't have, a route that shadows another, an unknown type in a signature, and a signature whose keywords differ from the method's. With `strict: true`, it also catches every untyped endpoint: one that has no signature at all, or whose signature types a keyword or the return as `untyped`.
516
520
 
517
521
  When your code raises at runtime, Skyward API responds with a 500 problem+json that carries the request ID and logs the exception. In development, the response also includes the backtrace.
518
522
 
@@ -680,15 +684,15 @@ This README is the spec, and this section lists each part of it that's built, as
680
684
 
681
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.
682
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.
683
- - **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:`. Source excerpts and "Did you mean" are still to come.
684
- - **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`. 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, and an `untyped` part of a body, such as an untyped endpoint's `body:`, 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.
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
+ - **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.
685
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.
686
690
  - **Providers.** The builder's `provide(name, provider)` registers anything that responds to `call(request)`, such as an object, a lambda or a `Method`, under a Symbol name, and raises `Skyward::Core::BootError` for a name that's already provided, or for `body` or `request`, which Skyward API fills itself. A keyword with a provided name is filled by its provider, never from the query string, and passed even when it has a default. On each request, once a route matches, each provider the endpoint asks for runs once, in keyword order, with the request, the same `Skyward::API::Request` that `request:` gets, before the body is read or any input is coerced, so a caller a provider turns away gets its response rather than a 422 that shows the inputs' shape. When a provider returns a response value (`Skyward::API::Responses::NoContent`, `Skyward::API::Responses::BadRequest`, `Skyward::API::Responses::Unauthorized`, `Skyward::API::Responses::Forbidden`, `Skyward::API::Responses::NotFound`, `Skyward::API::Responses::Conflict`, `Skyward::API::Responses::Unprocessable` or `Skyward::API::Responses::Redirect`), no later provider runs, the method never runs, and the value is answered as Responses below describes, written by the provider's return type, or by its own status for a provider with no signature; anything else it returns, `nil` and a `Skyward::API::Responses::Created` included, is the keyword's value. At boot, Skyward API reads the provider's signature: the `call` of its class, which may be inherited, or a `Method`'s own name, in either case read from the module that defines it. A provider whose `call` is defined on a single object, such as a module with `extend self` or a class with `def self.call`, has no signature Skyward API can read, so boot refuses it: provide an instance of a class. The response values in its return type are added to the document's responses of every endpoint that asks for its name, and the rest of the return type's members must be exactly the keyword's type's members, compared as RBS types in any order, with a `T?` as `T` and `nil`, so several members are compared as their union, and a return type of only response values matches no keyword; boot refuses a keyword that doesn't match. A provider with no signature, or whose `call` returns `untyped`, as a lambda's does, adds no responses and its value isn't checked. A provider that raises is answered with a 500, as Errors below describes, and so is a typed provider's response value that its return type doesn't list, which raises `Skyward::API::ReturnTypeError` naming the provider. A keyword typed `untyped`, nullable or not, as each of an untyped endpoint's keywords is, takes any provider's value unchecked, since untyped code isn't checked anywhere else, and is still filled by its provider, never from the query string, with the provider's responses still added to the endpoint's. With `strict: true`, a signature that types a provided keyword as `untyped`, nullable or not, is refused like one that types any other keyword so, but a provider with no signature, or whose `call` returns `untyped`, doesn't make the endpoints that ask for it untyped, since `strict:` refuses untyped endpoints, not providers.
687
- - **Responses.** An API's instances have private helpers that return frozen response values, each taking `headers:`: `created(value)` returns a `Skyward::API::Responses::Created[T]`, `no_content` a `Skyward::API::Responses::NoContent`, `bad_request(detail)` a `Skyward::API::Responses::BadRequest`, `unauthorized(detail)` a `Skyward::API::Responses::Unauthorized`, `forbidden(detail)` a `Skyward::API::Responses::Forbidden`, `not_found(detail = nil)` a `Skyward::API::Responses::NotFound`, `conflict(detail)` a `Skyward::API::Responses::Conflict`, `unprocessable(detail)` a `Skyward::API::Responses::Unprocessable` and `redirect(to, status: 303)` a `Skyward::API::Responses::Redirect`. `bad_request`, `unauthorized`, `forbidden` and `redirect` are also public module functions on `Skyward`, such as `Skyward.unauthorized("Sign in first")`, for code outside an API class. `redirect` raises `ArgumentError` for a `status:` other than 301, 302, 303, 307 or 308, or a `to` with a line break. At boot, each endpoint compiles a serializer for every member of its return type, and a returned value goes to the first member it fits: by class for a class with typed readers and for a response value, and by shape otherwise. A class with typed readers is written by calling each reader it declares, never `to_h`, and a record is read from a Hash by its declared keys, leaving out an optional key that's absent, so nothing undeclared is ever written. Integers, Floats, Strings and booleans are written as JSON, an enum's Symbol as its name, a `Date` as `YYYY-MM-DD`, a `Time` in UTC as ISO 8601 with six fractional digits (`2026-10-18T09:30:00.123456Z`), and `nil` only where the type is nullable. JSON has no `Infinity` or `NaN`, so `Float` fits only a finite Float. A `Hash[String, T]` writes each value as `T`, so a value's undeclared fields are dropped too, and String or Symbol keys as strings; a Hash with any other key doesn't fit it. A plain value answers 200 with `content-type: application/json`; `Skyward::API::Responses::Created[T]` answers 201 with its value written as `T`; `Skyward::API::Responses::NoContent` answers 204 with no body; `Skyward::API::Responses::BadRequest`, `Skyward::API::Responses::Unauthorized`, `Skyward::API::Responses::Forbidden`, `Skyward::API::Responses::NotFound`, `Skyward::API::Responses::Conflict` and `Skyward::API::Responses::Unprocessable` answer 400, 401, 403, 404, 409 and 422 with RFC 9457 `application/problem+json`, whose `detail` appears only when given; and `Skyward::API::Responses::Redirect` answers its status with a `location` header and no body. A response value's `headers:` are added to its response, and Skyward adds no `WWW-Authenticate` to a 401, so pass it in `headers:`. A part typed `untyped` is written as untyped code's is: scalars as themselves, Symbols as their names, dates and times as above, Hashes and Arrays item by item, and anything else through `to_h`; a return type of `untyped` also answers each response value with its own status. A value, or any part of it, that doesn't fit its type raises `Skyward::API::ReturnTypeError` before anything is written, naming the endpoint's label, what came back (a scalar's value, or else only its class) and where, and the type it should have been, so it's answered with a 500 as Errors below describes. Skyward API's signatures declare `Skyward::API::rack` as `[Integer, Hash[String, String], untyped]`, and a member typed with it, or with that tuple written out, takes an Array of an Integer, a Hash and a body, and sends it as given, without checking or rewriting any of it, so a body that streams through `each` or `call` works. An `Array[T]` member is always JSON, even for three items. The request ID is still added to a triple, and `HEAD` drops its body, closing it when it responds to `close`. An untyped endpoint's return type is `untyped`, so it's answered the same way. An untyped endpoint's Rack triples are still to come.
688
- - **OpenAPI document.** With `Skyward.app(docs: true)`, the app builds its OpenAPI 3.1 document once, at boot, and answers GET and HEAD at `/openapi.json` with it as `application/json`, before any route or static file. The same app always writes the same bytes. Its `info` has `Skyward.app`'s `title:` (`"API"` by default), `version:` (`"0.1.0"` by default) and, when given, `description:`. Each API class is a tag, in mount order, with its `description`, and each route is an operation under its path, with each path parameter as `{name}`, tagged with its class, with its `summary:` and `description:` when given and the operation ID `<Tag>_<method>`; a tag is the class's constant path with `::` as `.`. A path keyword is a required parameter, and a query keyword is a parameter, required when the method requires it and it isn't nullable, whose schema leaves out `null`. `body:` is an `application/json` request body, required on the same terms. Each member of the return type is a response: a plain type a 200 `application/json`, `Skyward::API::Responses::Created[T]` a 201 of `T`, `Skyward::API::Responses::NoContent` a 204, each problem its status with the `Problem` schema as `application/problem+json`, `Skyward::API::Responses::Redirect` a `3XX` with a `location` header, and `Skyward::API::rack` a `default` with no schema. The response values of each provider the endpoint asks for are its responses too. Members with the same status are one response, `oneOf` their schemas. `request:` and a provided keyword aren't part of the HTTP contract, so neither is a parameter, schema or component, or counts as an input. An endpoint with other keywords also lists 422, and one with `body:` 413 and 415, and the responses are ordered by status. `Integer`, `Float`, `String` and `bool` are `integer`, `number`, `string` and `boolean`, `Date` and `Time` are strings of format `date` and `date-time`, `untyped` is any value, a literal is a `const`, an enum is a string `enum`, `Array[T]` is an `array` of `T`, `Hash[String, T]` is an `object` whose `additionalProperties` is `T`'s schema, so `{}` for `untyped`, a record is an inline `object` with `required` naming its required keys, a union is `oneOf` its members, and a nullable type adds `null` to its `type`, except that a nullable enum, literal, union, class or `untyped` is `anyOf` it and `null`. A class with typed readers is a `$ref` to an `object` component named by its constant path with `::` as `.`, or by `Skyward.app(schema_names:)`. A nullable field is required in a response but not in a request, and a class reached from any keyword gets the request form. The components are ordered by name, and always include `Problem`, with `type`, `title` and `status` required and an optional `detail` and `errors`. With `docs: true`, boot refuses a route whose path is `/openapi.json`, a static file there, two operations with the same ID (which two routes to one method, or a class mounted twice, have), a schema name with anything but letters, digits, `.`, `-` and `_`, and two types with the same schema name, including `Problem`. An `untyped` path or query keyword is a `string`, since that's all either carries, and an untyped endpoint's body and 200 response are any value, `{}`.
691
+ - **Responses.** An API's instances have private helpers that return frozen response values, each taking `headers:`: `created(value)` returns a `Skyward::API::Responses::Created[T]`, `no_content` a `Skyward::API::Responses::NoContent`, `bad_request(detail)` a `Skyward::API::Responses::BadRequest`, `unauthorized(detail)` a `Skyward::API::Responses::Unauthorized`, `forbidden(detail)` a `Skyward::API::Responses::Forbidden`, `not_found(detail = nil)` a `Skyward::API::Responses::NotFound`, `conflict(detail)` a `Skyward::API::Responses::Conflict`, `unprocessable(detail)` a `Skyward::API::Responses::Unprocessable` and `redirect(to, status: 303)` a `Skyward::API::Responses::Redirect`. `bad_request`, `unauthorized`, `forbidden` and `redirect` are also public module functions on `Skyward`, such as `Skyward.unauthorized("Sign in first")`, for code outside an API class. `redirect` raises `ArgumentError` for a `status:` other than 301, 302, 303, 307 or 308, or a `to` with a line break. At boot, each endpoint compiles a serializer for every member of its return type, and a returned value goes to the first member it fits: by class for a class with typed readers and for a response value, and by shape otherwise. A class with typed readers is written by calling each reader it declares, never `to_h`, and a record is read from a Hash by its declared keys, leaving out an optional key that's absent, so nothing undeclared is ever written. Integers, Floats, Strings and booleans are written as JSON, an enum's Symbol as its name, a `Date` as `YYYY-MM-DD`, a `Time` in UTC as ISO 8601 with six fractional digits (`2026-10-18T09:30:00.123456Z`), a `BigDecimal` as a String of its digits with `to_s("F")`, which never uses an exponent and keeps no scale (`"12.5"` for `BigDecimal("12.50")`, `"100.0"`, `"-0.001"`), and `nil` only where the type is nullable. JSON has no `Infinity` or `NaN`, so `Float` fits only a finite Float, and `BigDecimal` only a finite BigDecimal. A `Hash[String, T]` writes each value as `T`, so a value's undeclared fields are dropped too, and String or Symbol keys as strings; a Hash with any other key doesn't fit it. A plain value answers 200 with `content-type: application/json`; `Skyward::API::Responses::Created[T]` answers 201 with its value written as `T`; `Skyward::API::Responses::NoContent` answers 204 with no body; `Skyward::API::Responses::BadRequest`, `Skyward::API::Responses::Unauthorized`, `Skyward::API::Responses::Forbidden`, `Skyward::API::Responses::NotFound`, `Skyward::API::Responses::Conflict` and `Skyward::API::Responses::Unprocessable` answer 400, 401, 403, 404, 409 and 422 with RFC 9457 `application/problem+json`, whose `detail` appears only when given; and `Skyward::API::Responses::Redirect` answers its status with a `location` header and no body. A response value's `headers:` are added to its response, and Skyward adds no `WWW-Authenticate` to a 401, so pass it in `headers:`. A part typed `untyped` is written as untyped code's is: scalars as themselves, Symbols as their names, dates, times and BigDecimals as above, Hashes and Arrays item by item, and anything else through `to_h`; a return type of `untyped` also answers each response value with its own status. A value, or any part of it, that doesn't fit its type raises `Skyward::API::ReturnTypeError` before anything is written, naming the endpoint's label, what came back (a scalar's value, or else only its class) and where, and the type it should have been, so it's answered with a 500 as Errors below describes. Skyward API's signatures declare `Skyward::API::rack` as `[Integer, Hash[String, String], untyped]`, and a member typed with it, or with that tuple written out, takes an Array of an Integer, a Hash and a body, and sends it as given, without checking or rewriting any of it, so a body that streams through `each` or `call` works. An `Array[T]` member is always JSON, even for three items. The request ID is still added to a triple, and `HEAD` drops its body, closing it when it responds to `close`. An untyped endpoint's return type is `untyped`, so it's answered the same way. Where a return type, or a member of one, is `untyped`, an `Array` of exactly three items, an `Integer` from 100 to 599, a `Hash`, and a body that responds to `each` or `call`, is sent as given, as a typed triple is, and anything else as above, so `[200, {}, "hi"]` is a JSON array. `untyped` inside a type, as in `Array[untyped]`, never sends a triple.
692
+ - **OpenAPI document.** With `Skyward.app(docs: true)`, the app builds its OpenAPI 3.1 document once, at boot, and answers GET and HEAD at `/openapi.json` with it as `application/json`, before any route or static file. The same app always writes the same bytes. Its `info` has `Skyward.app`'s `title:` (`"API"` by default), `version:` (`"0.1.0"` by default) and, when given, `description:`. Each API class is a tag, in mount order, with its `description`, and each route is an operation under its path, with each path parameter as `{name}`, tagged with its class, with its `summary:` and `description:` when given and the operation ID `<Tag>_<method>`; a tag is the class's constant path with `::` as `.`. A path keyword is a required parameter, and a query keyword is a parameter, required when the method requires it and it isn't nullable, whose schema leaves out `null`. `body:` is an `application/json` request body, required on the same terms. Each member of the return type is a response: a plain type a 200 `application/json`, `Skyward::API::Responses::Created[T]` a 201 of `T`, `Skyward::API::Responses::NoContent` a 204, each problem its status with the `Problem` schema as `application/problem+json`, `Skyward::API::Responses::Redirect` a `3XX` with a `location` header, and `Skyward::API::rack` a `default` with no schema. The response values of each provider the endpoint asks for are its responses too. Members with the same status are one response, `oneOf` their schemas. `request:` and a provided keyword aren't part of the HTTP contract, so neither is a parameter, schema or component, or counts as an input. An endpoint with other keywords also lists 422, and one with `body:` 413 and 415, and the responses are ordered by status. `Integer`, `Float`, `String` and `bool` are `integer`, `number`, `string` and `boolean`, `Date`, `Time` and `BigDecimal` are strings of format `date`, `date-time` and `decimal`, `untyped` is any value, a literal is a `const`, an enum is a string `enum`, `Array[T]` is an `array` of `T`, `Hash[String, T]` is an `object` whose `additionalProperties` is `T`'s schema, so `{}` for `untyped`, a record is an inline `object` with `required` naming its required keys, a union is `oneOf` its members, and a nullable type adds `null` to its `type`, except that a nullable enum, literal, union, class or `untyped` is `anyOf` it and `null`. A class with typed readers is a `$ref` to an `object` component named by its constant path with `::` as `.`, or by `Skyward.app(schema_names:)`. A nullable field is required in a response but not in a request, and a class reached from any keyword gets the request form. The components are ordered by name, and always include `Problem`, with `type`, `title` and `status` required and an optional `detail` and `errors`. With `docs: true`, boot refuses a route whose path is `/openapi.json`, a static file there, two operations with the same ID (which two routes to one method, or a class mounted twice, have), a schema name with anything but letters, digits, `.`, `-` and `_`, and two types with the same schema name, including `Problem`. An `untyped` path or query keyword is a `string`, since that's all either carries, and an untyped endpoint's body and 200 response are any value, `{}`.
689
693
  - **API reference.** With `docs: true`, the app also answers GET and HEAD at `/docs`, before any route or static file, with an HTML page built once, at boot, as `text/html; charset=utf-8`. Its title is `Skyward.app`'s `title:`, HTML-escaped. It points Scalar at the document by the relative URL `openapi.json`, so it works under a prefix, and loads Scalar from jsDelivr, as `@scalar/api-reference` 1.75.1's `dist/browser/standalone.js` with its `sha384` integrity hash and `crossorigin="anonymous"`, or else from `Skyward.app(scalar_url:)`, HTML-escaped, with no hash. It has no inline JavaScript: Scalar is configured through `data-url` and `data-configuration`, which turns off its default fonts. Another method at `/docs` is answered as if there were no page, and `/docs/` isn't served. With `docs: true`, boot refuses a route whose path is `/docs`, and a static file there.
690
694
  - **Request IDs.** The app `Skyward.app` returns gives every request an ID: an incoming `X-Request-Id` of 1 to 200 visible ASCII characters with no spaces, or else a random UUID from `SecureRandom`. The ID is stored in the Rack env as `skyward.request_id` before anything else runs, and every response carries it as `x-request-id`, replacing one the app set.
691
- - **HTTP's own answers.** A path that matches routes only under other methods gets a 405 problem+json with an `allow` header listing the methods of every route matching it, in the order `GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS`, with `HEAD` wherever there's `GET` and always `OPTIONS`. `HEAD` runs the GET route and answers its status and headers with an empty body. `OPTIONS` on a routed path answers 204 with `allow`, and on any other path 404. CORS is still to come.
695
+ - **HTTP's own answers.** A path that matches routes only under other methods gets a 405 problem+json with an `allow` header listing the methods of every route matching it, in the order `GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS`, with `HEAD` wherever there's `GET` and always `OPTIONS`. `HEAD` runs the GET route and answers its status and headers with an empty body. `OPTIONS` on a routed path answers 204 with `allow`, and on any other path 404.
692
696
  - **`skyward serve`.** Skyward API registers it with the `skyward` command. It runs the current directory's `config.ru`, needing no `app.rb`, under one Falcon process bound to `localhost`, on `PORT` (9292 by default), with `RACK_ENV=development` unless it's already set. It writes no files but `sig/generated`. With no `config.ru`, or no Falcon in the bundle `skyward` runs in, it exits 1 saying what to do. Under `bundle exec` that's the app's bundle; run bare, `skyward` sees every installed gem. It reloads the app when a `.rb`, `.rbs` or `config.ru` file under the directory is added, changed or removed, outside `tmp/`, `log/`, `vendor/`, `node_modules/` and hidden directories such as `.git/` and `.bundle/`, polling modification times at most once every half second. The first request after a change clears the routes and description of every API class defined in those files, drops those files from `$LOADED_FEATURES` so their `require`s run again, unloads and unregisters each Zeitwerk loader that manages only directories there (so `config.ru` can set it up again), reloads any other Zeitwerk loader with reloading enabled, and builds a new app from `config.ru`. When it starts, it first regenerates `sig/generated` with `Skyward::Core::Signatures::Inline.generate`, using the rbs-inline in that bundle, so the app loads the types the Ruby has now. Then it polls the same files in the background, at most once every half second, and regenerates `sig/generated` as soon as it sees a `.rb` file added, changed or removed, without waiting for a request, so Steep in your editor checks the types you just wrote. The reload still waits for the first request after the change, which regenerates first only if the background hasn't yet: rbs-inline runs once for the `.rb` files as they are, and never twice at once. Without rbs-inline in the bundle, it uses `sig/generated` as it is, runs nothing in the background, and says nothing about it. Regenerating writes only the files whose content changed, so it brings at most one more reload, of `.rbs` files alone, which doesn't regenerate. When rbs-inline fails, `sig/generated` is left as it was. A loader of the app's own needs reloading enabled: Zeitwerk can't unload one without it, or enable it after setup, so the reload fails saying to call `loader.enable_reloading` in development and restart. One reload runs at a time and requests wait for it, while a request in flight finishes on the app it started with. A load that raises, at boot or on a reload, including a `Skyward::Core::BootError` or a `SyntaxError`, answers every request until the next change retries it with the development 500 described under Errors: `type`, `title`, `status`, `detail` and `backtrace`, and an empty body for `HEAD`. So does rbs-inline failing, as a `Skyward::Core::BootError` that carries its output, with an empty `backtrace`. It has no `request_id`, because the app that assigns request IDs is the one that failed to load, and nothing is logged. Only `skyward serve` reloads.
693
697
  - **`skyward routes` and `skyward openapi`.** Skyward API registers them with the `skyward` command too. Each loads the current directory's `app.rb`, which must assign `App = Skyward.app { ... }`, after regenerating `sig/generated` as `skyward serve` does, or using it as it is without rbs-inline in the bundle. When rbs-inline fails, it exits 1 with rbs-inline's output, without loading `app.rb`. With no `app.rb`, or no `App` that's a Skyward app, it exits 1 naming the file and what it must assign, and a `Skyward::Core::BootError` exits 1 with its message and no backtrace. `skyward routes` prints a line per endpoint, in mount order and then declaration order: its verb, full path, `Class#method` and its method type as the signature file writes it, with a type wrapped over several lines put on one, or for an untyped endpoint as `(id: untyped, ?done: untyped) -> untyped`. Each column but the last is as wide as its widest entry, then two spaces. An app with no routes prints nothing. `skyward openapi` writes the document the OpenAPI document bullet above describes, as pretty JSON with a trailing newline, whether or not the app passed `docs: true`, so the same app always writes the same bytes. Without `docs: true`, a route or static file at `/openapi.json` or `/docs` doesn't stop it, but the document's other problems exit 1 with their message.
694
698
  - **`skyward check`.** Skyward API registers it with the `skyward` command. It checks the current directory's app three ways, in this order, writing `Signatures:`, `Strict boot:` or `Steep:` and then `passed` or `failed` as each finishes, followed by what it found, and runs every check even after one fails, then exits 1 if any failed and 0 otherwise. rbs-inline, the boot and Steep each run in a Ruby of their own, in the app's directory, with the gems of the bundle `skyward` runs in, as `skyward serve` describes, and nothing is written to the directory. **Signatures** runs rbs-inline, in its default opt-in mode, which reads only files marked `# rbs_inline: enabled`, over every `.rb` file in the directory outside `test/`, `spec/`, `vendor/`, `tmp/` and hidden directories, into a temporary directory. It fails when there's no `sig/generated`, or when the result differs from it, listing each file under `sig/generated` that's missing, out of date or not generated from any file, and either way gives the rbs-inline command that regenerates `sig/generated`. It also fails when rbs-inline does, with its output. **Strict boot** loads `app.rb` as `skyward routes` does, without regenerating `sig/generated`, with `SKYWARD_STRICT=1` in the environment, and fails where `skyward routes` would exit 1, with the same message, or on any other error, with its backtrace. It shows the boot's output even when it passes. **Steep** runs `steep check --no-daemon` with the app's `Steepfile`, and passes or fails as Steep does, with its output. Without rbs-inline or Steep in the bundle, or without a `Steepfile`, that check fails saying what to add.
@@ -23,6 +23,12 @@ module Skyward::API::Assembly::Boot
23
23
  # untyped, which is what rbs-inline writes for a method with no annotations.
24
24
  ANY = RBS::Types::Bases::Any.new(location: nil) #: RBS::Types::Bases::Any
25
25
 
26
+ Refusal = Data.define(
27
+ :problem, #: String
28
+ :spots, #: Array[Skyward::Core::Diagnostics::Spot]
29
+ :hint #: String?
30
+ )
31
+
26
32
  # @rbs (Array[Skyward::API::Assembly::Builder::Mount] mounts,
27
33
  # providers: Hash[Symbol, Skyward::API::_Provider & Object], reader: Skyward::Core::Types::Reader,
28
34
  # max_body_size: Integer, strict: bool) ->
@@ -32,12 +38,13 @@ module Skyward::API::Assembly::Boot
32
38
  raise Skyward::Core::BootError, single if single
33
39
 
34
40
  provided = providers.to_h { |name, callable| [name, provider(name, callable, reader)] }
35
- none = [] #: Array[Skyward::API::Routing::Router::Endpoint]
36
- built = mounts.reduce(none) do |booted, mount|
41
+ none = [] #: Array[[Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint]]
42
+ routed = mounts.reduce(none) do |booted, mount|
37
43
  mount.api.class.routes.reduce(booted) do |so_far, route|
38
- [*so_far, boot(mount, route, so_far, provided, reader, max_body_size)]
44
+ [*so_far, [route, boot(mount, route, so_far, provided, reader, max_body_size)]]
39
45
  end
40
46
  end
47
+ built = routed.map(&:last)
41
48
  return built unless strict
42
49
 
43
50
  refused = built.filter_map { |endpoint| untyped(endpoint, reader) }
@@ -82,7 +89,7 @@ module Skyward::API::Assembly::Boot
82
89
 
83
90
  # @rbs mount: Skyward::API::Assembly::Builder::Mount
84
91
  # @rbs route: Skyward::API::Endpoints::Route
85
- # @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
92
+ # @rbs built: Array[[Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint]]
86
93
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
87
94
  # @rbs reader: Skyward::Core::Types::Reader
88
95
  # @rbs max_body_size: Integer
@@ -92,20 +99,61 @@ module Skyward::API::Assembly::Boot
92
99
  verb = route.verb.upcase.name
93
100
  pattern = pattern(path)
94
101
  label = "#{mount.api.class}##{route.to} (#{verb} #{path})"
95
- result = summary(route) || shadowing(verb, pattern, built) ||
102
+ result = summary(route) || shadowing(route, verb, pattern, built) ||
96
103
  endpoint(mount.api, route, verb, pattern, label, providers, reader, max_body_size)
97
104
  case result
98
- when String then raise Skyward::Core::BootError, "#{label}\n #{result}"
105
+ when Refusal then raise Skyward::Core::BootError, explained(label, result)
99
106
  else result
100
107
  end
101
108
  end
102
109
 
110
+ # Core's own errors carry their excerpt in their message, already indented,
111
+ # so every line but an excerpt's is indented under the label.
112
+ # @rbs label: String
113
+ # @rbs refusal: Refusal
114
+ # @rbs return: String
115
+ def explained(label, refusal)
116
+ excerpt = Skyward::Core::Diagnostics::Excerpt.render(refusal.spots)
117
+ body = [[refusal.problem, excerpt].compact.join("\n\n"), refusal.hint].compact.join("\n")
118
+ lines = body.lines(chomp: true).map do |line|
119
+ line.empty? || line.start_with?(Skyward::Core::Diagnostics::Excerpt::INDENT) ? line : " #{line}"
120
+ end
121
+ [label, *lines].join("\n")
122
+ end
123
+
124
+ # @rbs problem: String
125
+ # @rbs spots: Array[Skyward::Core::Diagnostics::Spot?]
126
+ # @rbs hint: String?
127
+ # @rbs return: Refusal
128
+ def refused(problem, spots: [], hint: nil) = Refusal.new(problem:, spots: spots.compact, hint:)
129
+
103
130
  # @rbs route: Skyward::API::Endpoints::Route
104
- # @rbs return: String?
131
+ # @rbs key: Symbol
132
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
133
+ def argument(route, key)
134
+ file = route.file
135
+ line = route.line
136
+ Skyward::Core::Diagnostics::Spots.keyword_value(file, line, call: route.verb, key:) if file && line
137
+ end
138
+
139
+ # @rbs route: Skyward::API::Endpoints::Route
140
+ # @rbs part: String
141
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
142
+ def in_path(route, part)
143
+ file = route.file
144
+ line = route.line
145
+ Skyward::Core::Diagnostics::Spots.string(file, line, call: route.verb, part:) if file && line
146
+ end
147
+
148
+ # @rbs route: Skyward::API::Endpoints::Route
149
+ # @rbs return: Refusal?
105
150
  def summary(route)
106
151
  return unless route.summary&.match?(/\R/)
107
152
 
108
- "Its summary: has a line break, but a summary is one line. Put the rest in description:."
153
+ refused(
154
+ "Its summary: has a line break, but a summary is one line. Put the rest in description:.",
155
+ spots: [argument(route, :summary)]
156
+ )
109
157
  end
110
158
 
111
159
  # @rbs prefix: String
@@ -122,21 +170,25 @@ module Skyward::API::Assembly::Boot
122
170
  path.split("/", -1).map { |segment| segment.start_with?(":") ? segment.delete_prefix(":").to_sym : segment }
123
171
  end
124
172
 
173
+ # @rbs route: Skyward::API::Endpoints::Route
125
174
  # @rbs verb: String
126
175
  # @rbs pattern: Array[String | Symbol]
127
- # @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
128
- # @rbs return: String?
129
- def shadowing(verb, pattern, built)
130
- earlier = built.find { |endpoint| endpoint.verb == verb && covers?(endpoint.pattern, pattern) }
131
- return unless earlier
176
+ # @rbs built: Array[[Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint]]
177
+ # @rbs return: Refusal?
178
+ def shadowing(route, verb, pattern, built)
179
+ found = built.find { |_, endpoint| endpoint.verb == verb && covers?(endpoint.pattern, pattern) }
180
+ return unless found
132
181
 
133
- if covers?(pattern, earlier.pattern)
134
- "#{earlier.label} is tried first and matches exactly the same paths, so this route is never reached. " \
135
- "Remove one of them, or change a path."
136
- else
137
- "#{earlier.label} is tried first and matches every path this route does, so this route is never reached. " \
138
- "Declare the static route first."
139
- end
182
+ earlier_route, earlier = found
183
+ problem =
184
+ if covers?(pattern, earlier.pattern)
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."
187
+ else
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."
190
+ end
191
+ refused(problem, spots: [earlier_route, route].map { |declared| in_path(declared, declared.path) })
140
192
  end
141
193
 
142
194
  # A path parameter matches any segment but an empty one, which only the root path has.
@@ -156,36 +208,46 @@ module Skyward::API::Assembly::Boot
156
208
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
157
209
  # @rbs reader: Skyward::Core::Types::Reader
158
210
  # @rbs max_body_size: Integer
159
- # @rbs return: Skyward::API::Routing::Router::Endpoint | String
211
+ # @rbs return: Skyward::API::Routing::Router::Endpoint | Refusal
160
212
  def endpoint(api, route, verb, pattern, label, providers, reader, max_body_size)
161
- method_type = method_type(api.class, route.to, reader)
162
- return method_type if method_type.is_a?(String)
213
+ method_type = method_type(api.class, route, reader)
214
+ return method_type if method_type.is_a?(Refusal)
163
215
 
216
+ method = api.class.instance_method(route.to)
164
217
  function = method_type&.type
165
- signed = signed(api.class.instance_method(route.to).parameters, function)
166
- return signed if signed.is_a?(String)
218
+ signed = signed(method, function)
219
+ return signed if signed.is_a?(Refusal)
167
220
 
168
- unnamed = pattern.grep(Symbol).find { |name| signed.none? { |keyword, _, _| keyword == name } }
221
+ path_parameters = pattern.grep(Symbol) #: Array[Symbol]
222
+ unnamed = path_parameters.find { |name| signed.none? { |keyword, _, _| keyword == name } }
169
223
  if unnamed
170
- return "The route has a path parameter :#{unnamed}, but the method has no `#{unnamed}:` keyword. " \
171
- "Add `#{unnamed}:` to the method, or rename the path parameter."
224
+ query = signed.filter_map { |name, _, _| name if source(name, pattern) == :query && !providers.key?(name) }
225
+ return no_keyword(route, method, unnamed, query)
172
226
  end
173
227
 
174
- both = pattern.grep(Symbol).find { |name| providers.key?(name) }
228
+ both = path_parameters.find { |name| providers.key?(name) }
175
229
  if both
176
- return "The route has a path parameter :#{both}, but :#{both} is provided too, so `#{both}:` can't be both. " \
177
- "Rename the path parameter, or provide another name."
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."
232
+ return refused(
233
+ problem,
234
+ spots: [in_path(route, ":#{both}"), Skyward::Core::Diagnostics::Spots.keyword_parameter(method, both)]
235
+ )
178
236
  end
179
237
 
180
- read = signed.map { |name, required, type| keyword(name, required, type, pattern, providers, reader) }
181
- problem = read.find { |keyword| keyword.is_a?(String) }
182
- return problem if problem.is_a?(String)
238
+ read = signed.to_h { |name, required, type| [name, keyword(name, required, type, pattern, providers, reader)] }
239
+ name, problem = read.find { |_, keyword| keyword.is_a?(Refusal) }
240
+ if name && problem.is_a?(Refusal)
241
+ return problem.with(spots: [Skyward::Core::Diagnostics::Spots.keyword_parameter(method, name)].compact)
242
+ end
183
243
 
184
- keywords = read.grep(Skyward::API::Routing::Router::Keyword) #: Array[Skyward::API::Routing::Router::Keyword]
185
- provided = read.grep(Skyward::API::Routing::Router::Provider) #: Array[Skyward::API::Routing::Router::Provider]
244
+ keywords = read.values.grep(Skyward::API::Routing::Router::Keyword) #: Array[Skyward::API::Routing::Router::Keyword]
245
+ provided = read.values.grep(Skyward::API::Routing::Router::Provider) #: Array[Skyward::API::Routing::Router::Provider]
186
246
 
187
247
  returns = returns(function&.return_type || ANY, reader)
188
- return returns if returns.is_a?(String)
248
+ if returns.is_a?(Refusal)
249
+ return returns.with(spots: [Skyward::Core::Diagnostics::Spots.method_name(method)].compact)
250
+ end
189
251
 
190
252
  inputs = Skyward::API::Inputs.new(keywords, providers: provided, max_body_size:)
191
253
  serializer = Skyward::API::Serializer.new(returns, label:)
@@ -207,19 +269,38 @@ module Skyward::API::Assembly::Boot
207
269
  # The reader raises for a type it can't read at all, such as one that refers
208
270
  # to itself, and that's this route's problem too.
209
271
  rescue Skyward::Core::BootError => e
210
- e.message
272
+ refused(e.message)
211
273
  end
212
274
 
213
275
  # @rbs klass: Class
214
- # @rbs to: Symbol
276
+ # @rbs route: Skyward::API::Endpoints::Route
215
277
  # @rbs reader: Skyward::Core::Types::Reader
216
- # @rbs return: RBS::MethodType | String | nil
217
- def method_type(klass, to, reader)
218
- unless klass.public_method_defined?(to)
219
- return "#{klass} has no public method `#{to}`. Define it as a public method, or change to:."
220
- end
278
+ # @rbs return: RBS::MethodType | Refusal | nil
279
+ def method_type(klass, route, reader)
280
+ to = route.to
281
+ return signature(klass, to, reader) if klass.public_method_defined?(to)
282
+
283
+ refused(
284
+ "#{klass} has no public method `#{to}`. Define it as a public method, or change to:.",
285
+ spots: [argument(route, :to)],
286
+ hint: unrouted(klass, to)
287
+ )
288
+ end
289
+
290
+ # Only the class's own methods, so that a method it inherits, as from
291
+ # Skyward::API or Kernel, is never suggested.
292
+ # @rbs klass: Class
293
+ # @rbs to: Symbol
294
+ # @rbs return: String?
295
+ def unrouted(klass, to)
296
+ hidden =
297
+ if klass.private_method_defined?(to, false) then "private"
298
+ elsif klass.protected_method_defined?(to, false) then "protected"
299
+ end
300
+ return "#{to} is #{hidden}. Move it above `#{hidden}`." if hidden
221
301
 
222
- signature(klass, to, reader)
302
+ closest = Skyward::Core::Diagnostics::Suggestion.closest(to.to_s, klass.public_instance_methods(false).map(&:to_s))
303
+ "Did you mean to: :#{closest}?" if closest
223
304
  end
224
305
 
225
306
  # @rbs owner: Module
@@ -231,13 +312,17 @@ module Skyward::API::Assembly::Boot
231
312
  reader.method_type(type_name, name) if type_name
232
313
  end
233
314
 
234
- # @rbs parameters: Method::param_types
315
+ # @rbs method: UnboundMethod
235
316
  # @rbs type: RBS::Types::function?
236
- # @rbs return: Array[[Symbol, bool, RBS::Types::t]] | String
237
- def signed(parameters, type)
317
+ # @rbs return: Array[[Symbol, bool, RBS::Types::t]] | Refusal
318
+ def signed(method, type)
319
+ parameters = method.parameters
238
320
  if parameters.any? { |kind, _| UNNAMED.include?(kind) }
239
- return "The method takes positional arguments or **rest, but Skyward API passes only named keywords. " \
240
- "Take each input as a keyword, such as `id:`."
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:`.",
324
+ spots: [Skyward::Core::Diagnostics::Spots.parameters(method)]
325
+ )
241
326
  end
242
327
 
243
328
  keywords = parameters.filter_map { |kind, name| [name, kind == :keyreq] if KEYWORD.include?(kind) }.to_h
@@ -268,11 +353,13 @@ module Skyward::API::Assembly::Boot
268
353
 
269
354
  # @rbs keywords: Hash[Symbol, bool]
270
355
  # @rbs function: RBS::Types::function
271
- # @rbs return: String
356
+ # @rbs return: Refusal
272
357
  def stale(keywords, function)
273
358
  taken = keywords.map { |name, required| "#{"?" unless required}#{name}:" }
274
- "The method takes (#{taken.join(", ")}), but its signature takes (#{written(function.param_to_s)}), " \
359
+ refused(
360
+ "The method takes (#{taken.join(", ")}), but its signature takes (#{written(function.param_to_s)}), " \
275
361
  "so the signature is stale. Run rbs-inline, or update the signature."
362
+ )
276
363
  end
277
364
 
278
365
  # @rbs function: RBS::Types::function
@@ -297,13 +384,61 @@ module Skyward::API::Assembly::Boot
297
384
  function.required_keywords.transform_values { true }.merge(function.optional_keywords.transform_values { false })
298
385
  end
299
386
 
387
+ # @rbs route: Skyward::API::Endpoints::Route
388
+ # @rbs method: UnboundMethod
389
+ # @rbs parameter: Symbol
390
+ # @rbs query: Array[Symbol]
391
+ # @rbs return: Refusal
392
+ def no_keyword(route, method, parameter, query)
393
+ problem = "The route has a path parameter :#{parameter}, but the method has no `#{parameter}:` keyword. " \
394
+ "Add `#{parameter}:` to the method, or rename the path parameter."
395
+ meant = meant(parameter, query)
396
+ keyword = Skyward::Core::Diagnostics::Spots.keyword_parameter(method, meant) if meant
397
+ parameters = Skyward::Core::Diagnostics::Spots.parameters(method)
398
+ hint = rename_hint(method, parameters, keyword, parameter) if parameters && keyword
399
+ refused(problem, spots: [argument(route, :to)&.with(columns: nil), keyword || parameters], hint:)
400
+ end
401
+
402
+ # A nested resource's renamed parameter, as `todo_id:` for `/:id`, isn't a
403
+ # misspelling DidYouMean would find, so a keyword that ends in the parameter,
404
+ # or that the parameter ends in, is meant too, when it's the only one.
405
+ # @rbs parameter: Symbol
406
+ # @rbs query: Array[Symbol]
407
+ # @rbs return: Symbol?
408
+ def meant(parameter, query)
409
+ closest = Skyward::Core::Diagnostics::Suggestion.closest(parameter.to_s, query.map(&:to_s))
410
+ return closest.to_sym if closest
411
+
412
+ suffixed = query.select { |name| name.end_with?("_#{parameter}") || parameter.end_with?("_#{name}") }
413
+ suffixed.first if suffixed.one?
414
+ end
415
+
416
+ # Core's spot of a parameter list that runs onto another line stops at the end
417
+ # of its first, so only a list written whole on the `def` line is rewritten.
418
+ # @rbs method: UnboundMethod
419
+ # @rbs parameters: Skyward::Core::Diagnostics::Spot
420
+ # @rbs keyword: Skyward::Core::Diagnostics::Spot
421
+ # @rbs parameter: Symbol
422
+ # @rbs return: String?
423
+ def rename_hint(method, parameters, keyword, parameter)
424
+ list = parameters.columns
425
+ columns = keyword.columns
426
+ text = parameters.text
427
+ line = method.source_location&.last
428
+ return unless list && columns && parameters.line == line && text[list.end] == ")" && keyword.line == line
429
+
430
+ renamed = text[columns].to_s.sub(/\A[^:]+/, parameter.to_s)
431
+ rewritten = "#{text[list.begin...columns.begin]}#{renamed}#{text[columns.end...list.end]}"
432
+ "Did you mean `def #{method.original_name}(#{rewritten})`?"
433
+ end
434
+
300
435
  # @rbs name: Symbol
301
436
  # @rbs required: bool
302
437
  # @rbs type: RBS::Types::t
303
438
  # @rbs pattern: Array[String | Symbol]
304
439
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
305
440
  # @rbs reader: Skyward::Core::Types::Reader
306
- # @rbs return: Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | String
441
+ # @rbs return: Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | Refusal
307
442
  def keyword(name, required, type, pattern, providers, reader)
308
443
  source = source(name, pattern)
309
444
  return request(required, type) if source == :request
@@ -332,11 +467,13 @@ module Skyward::API::Assembly::Boot
332
467
 
333
468
  # @rbs required: bool
334
469
  # @rbs type: RBS::Types::t
335
- # @rbs return: Skyward::API::Routing::Router::Keyword | String
470
+ # @rbs return: Skyward::API::Routing::Router::Keyword | Refusal
336
471
  def request(required, type)
337
472
  unless [REQUEST, ANY].include?(type)
338
- return "`request:` is always the Skyward::API::Request, but its signature types it as #{written(type.to_s)}. " \
339
- "Type it as Skyward::API::Request, or rename the keyword."
473
+ return refused(
474
+ "`request:` is always the Skyward::API::Request, but its signature types it as " \
475
+ "#{written(type.to_s)}. Type it as Skyward::API::Request, or rename the keyword."
476
+ )
340
477
  end
341
478
 
342
479
  Skyward::API::Routing::Router::Keyword.new(name: :request, source: :request, required:, type: REQUEST_TYPE)
@@ -347,14 +484,16 @@ module Skyward::API::Assembly::Boot
347
484
  # @rbs name: Symbol
348
485
  # @rbs type: RBS::Types::t
349
486
  # @rbs provider: Skyward::API::Routing::Router::Provider
350
- # @rbs return: Skyward::API::Routing::Router::Provider | String
487
+ # @rbs return: Skyward::API::Routing::Router::Provider | Refusal
351
488
  def provided(name, type, provider)
352
489
  value = provider.value
353
490
  return provider if value.nil? || untyped_type?(type) || same?(parts(type), value)
354
491
 
355
492
  returned = value.empty? ? "only responses" : "#{written(value.join(" | "))}, besides any responses"
356
- "`#{name}:` is typed as #{written(type.to_s)}, but the :#{name} provider returns #{returned}. " \
493
+ refused(
494
+ "`#{name}:` is typed as #{written(type.to_s)}, but the :#{name} provider returns #{returned}. " \
357
495
  "Give them the same type."
496
+ )
358
497
  end
359
498
 
360
499
  # @rbs type: RBS::Types::t
@@ -370,20 +509,24 @@ module Skyward::API::Assembly::Boot
370
509
  # @rbs name: Symbol
371
510
  # @rbs source: :path | :query | :body | :request
372
511
  # @rbs type: Skyward::Core::Types::t
373
- # @rbs return: String?
512
+ # @rbs return: Refusal?
374
513
  def carried(name, source, type)
375
514
  case source
376
515
  when :path
377
516
  uncarried = uncarried(type, :path)
378
517
  if uncarried
379
- "`#{name}:` comes from the path, which can't carry #{uncarried}. " \
518
+ refused(
519
+ "`#{name}:` comes from the path, which can't carry #{uncarried}. " \
380
520
  "Give it a type such as String, Integer or an enum."
521
+ )
381
522
  end
382
523
  when :query
383
524
  uncarried = uncarried(type, :query)
384
525
  if uncarried
385
- "`#{name}:` comes from the query string, which can't carry #{uncarried}. " \
526
+ refused(
527
+ "`#{name}:` comes from the query string, which can't carry #{uncarried}. " \
386
528
  "Give it a type such as String, Integer or an array of them, or take it in `body:`."
529
+ )
387
530
  end
388
531
  end
389
532
  end
@@ -410,7 +553,7 @@ module Skyward::API::Assembly::Boot
410
553
  # Response values are found in the signature, because the reader can't read them.
411
554
  # @rbs type: RBS::Types::t
412
555
  # @rbs reader: Skyward::Core::Types::Reader
413
- # @rbs return: Array[Skyward::API::Routing::Router::returned] | String
556
+ # @rbs return: Array[Skyward::API::Routing::Router::returned] | Refusal
414
557
  def returns(type, reader)
415
558
  read = parts(type).map { |part| response(part, reader) || reader.read(part) }
416
559
  unreadable = read.find { |member| member.is_a?(Skyward::Core::Types::Unreadable) }
@@ -457,7 +600,8 @@ module Skyward::API::Assembly::Boot
457
600
  # @rbs return: Skyward::API::Routing::Router::Created | Skyward::Core::Types::Unreadable
458
601
  def created(type, reader)
459
602
  unless type.args.size == 1
460
- return Skyward::Core::Types::Unreadable.new(type: written(type.to_s), at: nil, instead: "Skyward::API::Responses::Created[T]")
603
+ instead = "Skyward::API::Responses::Created[T]"
604
+ return Skyward::Core::Types::Unreadable.new(type: written(type.to_s), at: nil, instead:, suggestion: nil)
461
605
  end
462
606
 
463
607
  read = reader.read(type.args.fetch(0))
@@ -521,10 +665,14 @@ module Skyward::API::Assembly::Boot
521
665
 
522
666
  # @rbs subject: String
523
667
  # @rbs type: Skyward::Core::Types::Unreadable
524
- # @rbs return: String
668
+ # @rbs return: Refusal
525
669
  def unreadable(subject, type)
526
- "#{subject} can't be read: Skyward API doesn't read #{type.type}#{", at #{type.at}" if type.at}. " \
527
- "Use #{type.instead} instead."
670
+ suggestion = type.suggestion
671
+ refused(
672
+ "#{subject} can't be read: Skyward API doesn't read #{type.type}#{", at #{type.at}" if type.at}. " \
673
+ "Use #{type.instead} instead.",
674
+ hint: ("Did you mean #{suggestion}?" if suggestion)
675
+ )
528
676
  end
529
677
 
530
678
  # @rbs text: String
@@ -95,12 +95,16 @@ module Skyward::API::Endpoints::Declarations
95
95
  problem = problem_with(path, to)
96
96
  raise ArgumentError, "#{self} #{verb.upcase} #{path.inspect}: #{problem}" if problem
97
97
 
98
+ # The caller of get, post, put, patch or delete, which is the app's declaration.
99
+ location = caller_locations(2, 1)&.first
98
100
  route = Skyward::API::Endpoints::Route.new(
99
101
  verb:,
100
102
  path: path.dup.freeze,
101
103
  to:,
102
104
  summary: summary.dup.freeze,
103
- description: description.dup.freeze
105
+ description: description.dup.freeze,
106
+ file: location&.path,
107
+ line: location&.lineno
104
108
  )
105
109
  @routes = [*routes, route].freeze
106
110
  end
@@ -8,6 +8,8 @@ module Skyward::API::Endpoints
8
8
  :path, #: String
9
9
  :to, #: Symbol
10
10
  :summary, #: String?
11
- :description #: String?
11
+ :description, #: String?
12
+ :file, #: String?
13
+ :line #: Integer?
12
14
  )
13
15
  end
@@ -38,10 +38,15 @@ module Skyward::API::Inputs::Coercer
38
38
  # none of them.
39
39
  MISFIT = Invalid.new(errors: [Error.new(at: "", message: "doesn't fit")]) #: Invalid
40
40
 
41
- # INTEGER, DATE and TIME match a String's bytes, because a path parameter
42
- # can be any bytes, and Regexp#match raises on a String that isn't UTF-8.
41
+ # INTEGER, DECIMAL, DATE and TIME match a String's bytes, because a path
42
+ # parameter can be any bytes, and Regexp#match raises on a String that isn't
43
+ # UTF-8.
43
44
  INTEGER = /\A-?\d+\z/ #: Regexp
44
45
 
46
+ # No exponent, NaN or Infinity: "1e1000000000" is short, but written without
47
+ # an exponent it's a billion digits long.
48
+ DECIMAL = /\A-?\d+(?:\.\d+)?\z/ #: Regexp
49
+
45
50
  BOOLEANS = { "true" => true, "false" => false, "1" => true, "0" => false }.freeze #: Hash[String, bool]
46
51
 
47
52
  DATE = /\A(\d{4})-(\d{2})-(\d{2})\z/ #: Regexp
@@ -60,10 +65,22 @@ module Skyward::API::Inputs::Coercer
60
65
  bool: "bool",
61
66
  date: "Date",
62
67
  time: "Time",
68
+ decimal: "BigDecimal",
63
69
  untyped: "untyped"
64
70
  }.freeze #: Hash[Skyward::Core::Types::scalar, String]
65
71
 
66
- FORMATS = { date: "Date (YYYY-MM-DD)", time: "Time (ISO 8601)" }.freeze #: Hash[Skyward::Core::Types::scalar, String]
72
+ FORMATS = {
73
+ date: "Date (YYYY-MM-DD)",
74
+ time: "Time (ISO 8601)",
75
+ decimal: 'BigDecimal (a decimal string, such as "12.50")'
76
+ }.freeze #: Hash[Skyward::Core::Types::scalar, String]
77
+
78
+ # A Hash[String, T] says its keys are Strings, so an untyped value it holds
79
+ # keeps the JSON's String keys at every level.
80
+ AS_PARSED = [
81
+ Skyward::Core::Types::Scalar.new(name: :untyped),
82
+ Skyward::Core::Types::Nullable.new(type: Skyward::Core::Types::Scalar.new(name: :untyped))
83
+ ].freeze #: Array[Skyward::Core::Types::t]
67
84
 
68
85
  # Path and query values are Strings, so with strings: true a coercer parses them.
69
86
  # @rbs type: Skyward::Core::Types::t
@@ -113,11 +130,14 @@ module Skyward::API::Inputs::Coercer
113
130
  when Skyward::Core::Types::Enum then enum(type.symbols, expected)
114
131
  when Skyward::Core::Types::Nullable then nullable(build(type.type, strings, member, unions))
115
132
  when Skyward::Core::Types::ArrayOf then array(build(type.type, strings, member, unions), strings, limit, expected)
116
- when Skyward::Core::Types::HashOf then hash_of(build(type.type, strings, member, unions), limit, expected)
133
+ when Skyward::Core::Types::HashOf
134
+ value = AS_PARSED.include?(type.type) ? as_parsed : build(type.type, strings, member, unions)
135
+ hash_of(value, limit, expected)
117
136
  when Skyward::Core::Types::Record then object(fields(type, strings, member, unions), limit, expected, &:itself)
118
137
  when Skyward::Core::Types::Named
119
138
  klass = type.klass
120
139
  object(fields(type, strings, member, unions), limit, expected) { |values| klass.new(**values) }
140
+ when Skyward::Core::Types::Refined then build(type.type, strings, member, unions)
121
141
  # Equal unions share one coercer, which is what lets one remember its results.
122
142
  else unions[[type, member]] ||= union(type.types.map { |one| build(one, strings, true, unions) }, member, expected)
123
143
  end
@@ -148,6 +168,7 @@ module Skyward::API::Inputs::Coercer
148
168
  when :string then ->(raw) { Ok.new(value: raw) if raw.is_a?(String) }
149
169
  when :date then ->(raw) { date(raw) }
150
170
  when :time then ->(raw) { time(raw) }
171
+ when :decimal then ->(raw) { decimal(raw) }
151
172
  else ->(raw) { Ok.new(value: strings ? last(raw) : symbolized(raw)) }
152
173
  end
153
174
  end
@@ -158,6 +179,9 @@ module Skyward::API::Inputs::Coercer
158
179
  # @rbs return: String?
159
180
  def last(raw) = raw.is_a?(Array) ? raw.last : raw
160
181
 
182
+ # @rbs return: coercer
183
+ def as_parsed = ->(raw, _at, _seen) { Ok.new(value: raw) }
184
+
161
185
  # @rbs raw: untyped
162
186
  # @rbs return: untyped
163
187
  def symbolized(raw)
@@ -224,6 +248,14 @@ module Skyward::API::Inputs::Coercer
224
248
  Ok.new(value: Time.new(on.year, on.month, on.day, hour.to_i, minute.to_i, seconds, zone))
225
249
  end
226
250
 
251
+ # A JSON number isn't one, because JSON.parse has already made it a Float,
252
+ # which may have lost digits.
253
+ # @rbs raw: untyped
254
+ # @rbs return: Ok?
255
+ def decimal(raw)
256
+ Ok.new(value: BigDecimal(raw)) if raw.is_a?(String) && DECIMAL.match?(raw.b)
257
+ end
258
+
227
259
  # @rbs value: Skyward::Core::Types::literal
228
260
  # @rbs strings: bool
229
261
  # @rbs expected: String?
@@ -411,6 +443,7 @@ module Skyward::API::Inputs::Coercer
411
443
  fields = type.fields.map { |field| "#{"?" unless field.required}#{field.name}: #{written(field.type)}" }
412
444
  "{ #{fields.join(", ")} }"
413
445
  when Skyward::Core::Types::Named then type.name
446
+ when Skyward::Core::Types::Refined then written(type.type)
414
447
  else type.types.map { |member| written(member) }.join(" | ")
415
448
  end
416
449
  end
@@ -36,6 +36,7 @@ module Skyward::API::OpenAPI
36
36
  bool: { type: "boolean" },
37
37
  date: { type: "string", format: "date" },
38
38
  time: { type: "string", format: "date-time" },
39
+ decimal: { type: "string", format: "decimal" },
39
40
  untyped: {} #: schema
40
41
  }.freeze #: Hash[Skyward::Core::Types::scalar, schema]
41
42
 
@@ -345,6 +346,7 @@ module Skyward::API::OpenAPI
345
346
  when Skyward::Core::Types::HashOf then { type: "object", additionalProperties: schema(type.type, form, names) }
346
347
  when Skyward::Core::Types::Record then object(type.fields, form, names)
347
348
  when Skyward::Core::Types::Named then { "$ref": "#/components/schemas/#{names.fetch(type.klass)}" }
349
+ when Skyward::Core::Types::Refined then schema(type.type, form, names)
348
350
  else { oneOf: type.types.map { |member| schema(member, form, names) } }
349
351
  end
350
352
  end
@@ -32,6 +32,7 @@ module Skyward::API::Serializer::Writers
32
32
  when Skyward::Core::Types::Record then record(type.fields)
33
33
  when Skyward::Core::Types::Named then named(type)
34
34
  when Skyward::Core::Types::Union then union(type.types.map { |member| writer(member) })
35
+ when Skyward::Core::Types::Refined then writer(type.type)
35
36
  end
36
37
  end
37
38
 
@@ -88,6 +89,8 @@ module Skyward::API::Serializer::Writers
88
89
  when :bool then checked("bool", ->(value) { [true, false].include?(value) }, ->(value, _) { value })
89
90
  when :date then checked("Date", ->(value) { value.is_a?(Date) }, ->(value, _) { date(value) })
90
91
  when :time then checked("Time", ->(value) { value.is_a?(Time) }, ->(value, _) { time(value) })
92
+ when :decimal
93
+ checked("BigDecimal", ->(value) { value.is_a?(BigDecimal) && value.finite? }, ->(value, _) { decimal(value) })
91
94
  when :untyped then Writer.new(name: "untyped", fits: ->(_) { true }, write: ->(value, at) { untyped(value, at) })
92
95
  end
93
96
  end
@@ -188,6 +191,12 @@ module Skyward::API::Serializer::Writers
188
191
  # @rbs return: String
189
192
  def time(value) = value.getutc.iso8601(6)
190
193
 
194
+ # A String, so a client that reads JSON numbers as doubles keeps every digit,
195
+ # and "F" so it never has an exponent.
196
+ # @rbs value: BigDecimal
197
+ # @rbs return: String
198
+ def decimal(value) = value.to_s("F")
199
+
191
200
  # @rbs value: untyped
192
201
  # @rbs at: String
193
202
  # @rbs return: untyped
@@ -197,6 +206,7 @@ module Skyward::API::Serializer::Writers
197
206
  when Symbol then value.name
198
207
  when Date then date(value)
199
208
  when Time then time(value)
209
+ when BigDecimal then value.finite? ? decimal(value) : misfit("BigDecimal", value, at)
200
210
  when Hash then object(value.map { |key, item| [key, untyped(item, "#{at}.#{key}")] })
201
211
  when Array then items(value.each_with_index.map { |item, index| untyped(item, "#{at}[#{index}]") })
202
212
  else value.respond_to?(:to_h) ? untyped(value.to_h, at) : misfit("something with to_h", value, at)
@@ -223,6 +233,7 @@ module Skyward::API::Serializer::Writers
223
233
  got =
224
234
  case value
225
235
  when nil, true, false, Symbol, Integer, Float then value.inspect
236
+ when BigDecimal then decimal(value)
226
237
  else value.class.inspect
227
238
  end
228
239
  Misfit.new(at:, expected:, got:)
@@ -65,11 +65,11 @@ class Skyward::API::Serializer
65
65
  end
66
66
  end
67
67
 
68
- # Untyped code can return any response value.
68
+ # Untyped code can return any response value, or a Rack triple.
69
69
  # @rbs return: Writers::Writer
70
70
  def untyped
71
71
  writer = Writers.writer(UNTYPED)
72
- responses = [created(writer), *RESPONSES.map { |klass| response(klass) }, ok(writer)]
72
+ responses = [created(writer), *RESPONSES.map { |klass| response(klass) }, untyped_rack, ok(writer)]
73
73
  Writers.union(responses).with(name: "untyped")
74
74
  end
75
75
 
@@ -105,11 +105,29 @@ class Skyward::API::Serializer
105
105
 
106
106
  # @rbs return: Writers::Writer
107
107
  def rack
108
- Writers.checked(
109
- "Skyward::API::rack",
110
- ->(given) { given.is_a?(Array) && given.size == 3 && given[0].is_a?(Integer) && given[1].is_a?(Hash) },
111
- ->(given, _) { given }
112
- )
108
+ rack_writer(->(given) { given.is_a?(Array) && given.size == 3 && given[0].is_a?(Integer) && given[1].is_a?(Hash) })
109
+ end
110
+
111
+ # Nothing typed says an untyped value is a triple, so it must have a status HTTP has and a body Rack can send.
112
+ # @rbs return: Writers::Writer
113
+ def untyped_rack
114
+ rack_writer(->(given) { triple?(given) })
115
+ end
116
+
117
+ # @rbs fits: ^(untyped) -> bool
118
+ # @rbs return: Writers::Writer
119
+ def rack_writer(fits)
120
+ Writers.checked("Skyward::API::rack", fits, ->(given, _) { given })
121
+ end
122
+
123
+ # @rbs given: untyped
124
+ # @rbs return: bool
125
+ def triple?(given)
126
+ return false unless given.is_a?(Array) && given.size == 3
127
+
128
+ status, headers, body = given
129
+ status.is_a?(Integer) && status.between?(100, 599) && headers.is_a?(Hash) &&
130
+ (body.respond_to?(:each) || body.respond_to?(:call))
113
131
  end
114
132
 
115
133
  # @rbs problem: Problem
@@ -4,7 +4,7 @@ module Skyward
4
4
  class API
5
5
  # x-release-please-start-version
6
6
 
7
- VERSION = "0.3.0" #: String
7
+ VERSION = "0.4.0" #: String
8
8
 
9
9
  # x-release-please-end
10
10
  end
data/lib/skyward/api.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "bigdecimal"
3
4
  require "securerandom"
4
5
  require "skyward/core"
5
6
  require "zeitwerk"
@@ -15,6 +15,21 @@ module Skyward::API::Assembly::Boot
15
15
  # untyped, which is what rbs-inline writes for a method with no annotations.
16
16
  ANY: RBS::Types::Bases::Any
17
17
 
18
+ class Refusal < Data
19
+ attr_reader problem(): String
20
+
21
+ attr_reader spots(): Array[Skyward::Core::Diagnostics::Spot]
22
+
23
+ attr_reader hint(): String?
24
+
25
+ def self.new: (String problem, Array[Skyward::Core::Diagnostics::Spot] spots, String? hint) -> instance
26
+ | (problem: String, spots: Array[Skyward::Core::Diagnostics::Spot], hint: String?) -> instance
27
+
28
+ def self.members: () -> [ :problem, :spots, :hint ]
29
+
30
+ def members: () -> [ :problem, :spots, :hint ]
31
+ end
32
+
18
33
  # @rbs (Array[Skyward::API::Assembly::Builder::Mount] mounts,
19
34
  # providers: Hash[Symbol, Skyward::API::_Provider & Object], reader: Skyward::Core::Types::Reader,
20
35
  # max_body_size: Integer, strict: bool) ->
@@ -36,16 +51,39 @@ module Skyward::API::Assembly::Boot
36
51
 
37
52
  # @rbs mount: Skyward::API::Assembly::Builder::Mount
38
53
  # @rbs route: Skyward::API::Endpoints::Route
39
- # @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
54
+ # @rbs built: Array[[Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint]]
40
55
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
41
56
  # @rbs reader: Skyward::Core::Types::Reader
42
57
  # @rbs max_body_size: Integer
43
58
  # @rbs return: Skyward::API::Routing::Router::Endpoint
44
- def boot: (Skyward::API::Assembly::Builder::Mount mount, Skyward::API::Endpoints::Route route, Array[Skyward::API::Routing::Router::Endpoint] built, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader, Integer max_body_size) -> Skyward::API::Routing::Router::Endpoint
59
+ def boot: (Skyward::API::Assembly::Builder::Mount mount, Skyward::API::Endpoints::Route route, Array[[ Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint ]] built, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader, Integer max_body_size) -> Skyward::API::Routing::Router::Endpoint
60
+
61
+ # Core's own errors carry their excerpt in their message, already indented,
62
+ # so every line but an excerpt's is indented under the label.
63
+ # @rbs label: String
64
+ # @rbs refusal: Refusal
65
+ # @rbs return: String
66
+ def explained: (String label, Refusal refusal) -> String
67
+
68
+ # @rbs problem: String
69
+ # @rbs spots: Array[Skyward::Core::Diagnostics::Spot?]
70
+ # @rbs hint: String?
71
+ # @rbs return: Refusal
72
+ def refused: (String problem, ?spots: Array[Skyward::Core::Diagnostics::Spot?], ?hint: String?) -> Refusal
45
73
 
46
74
  # @rbs route: Skyward::API::Endpoints::Route
47
- # @rbs return: String?
48
- def summary: (Skyward::API::Endpoints::Route route) -> String?
75
+ # @rbs key: Symbol
76
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
77
+ def argument: (Skyward::API::Endpoints::Route route, Symbol key) -> Skyward::Core::Diagnostics::Spot?
78
+
79
+ # @rbs route: Skyward::API::Endpoints::Route
80
+ # @rbs part: String
81
+ # @rbs return: Skyward::Core::Diagnostics::Spot?
82
+ def in_path: (Skyward::API::Endpoints::Route route, String part) -> Skyward::Core::Diagnostics::Spot?
83
+
84
+ # @rbs route: Skyward::API::Endpoints::Route
85
+ # @rbs return: Refusal?
86
+ def summary: (Skyward::API::Endpoints::Route route) -> Refusal?
49
87
 
50
88
  # @rbs prefix: String
51
89
  # @rbs path: String
@@ -56,11 +94,12 @@ module Skyward::API::Assembly::Boot
56
94
  # @rbs return: Array[String | Symbol]
57
95
  def pattern: (String path) -> Array[String | Symbol]
58
96
 
97
+ # @rbs route: Skyward::API::Endpoints::Route
59
98
  # @rbs verb: String
60
99
  # @rbs pattern: Array[String | Symbol]
61
- # @rbs built: Array[Skyward::API::Routing::Router::Endpoint]
62
- # @rbs return: String?
63
- def shadowing: (String verb, Array[String | Symbol] pattern, Array[Skyward::API::Routing::Router::Endpoint] built) -> String?
100
+ # @rbs built: Array[[Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint]]
101
+ # @rbs return: Refusal?
102
+ def shadowing: (Skyward::API::Endpoints::Route route, String verb, Array[String | Symbol] pattern, Array[[ Skyward::API::Endpoints::Route, Skyward::API::Routing::Router::Endpoint ]] built) -> Refusal?
64
103
 
65
104
  # A path parameter matches any segment but an empty one, which only the root path has.
66
105
  # @rbs pattern: Array[String | Symbol]
@@ -76,14 +115,21 @@ module Skyward::API::Assembly::Boot
76
115
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
77
116
  # @rbs reader: Skyward::Core::Types::Reader
78
117
  # @rbs max_body_size: Integer
79
- # @rbs return: Skyward::API::Routing::Router::Endpoint | String
80
- def endpoint: (Skyward::API api, Skyward::API::Endpoints::Route route, String verb, Array[String | Symbol] pattern, String label, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader, Integer max_body_size) -> (Skyward::API::Routing::Router::Endpoint | String)
118
+ # @rbs return: Skyward::API::Routing::Router::Endpoint | Refusal
119
+ def endpoint: (Skyward::API api, Skyward::API::Endpoints::Route route, String verb, Array[String | Symbol] pattern, String label, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader, Integer max_body_size) -> (Skyward::API::Routing::Router::Endpoint | Refusal)
81
120
 
82
121
  # @rbs klass: Class
83
- # @rbs to: Symbol
122
+ # @rbs route: Skyward::API::Endpoints::Route
84
123
  # @rbs reader: Skyward::Core::Types::Reader
85
- # @rbs return: RBS::MethodType | String | nil
86
- def method_type: (Class klass, Symbol to, Skyward::Core::Types::Reader reader) -> (RBS::MethodType | String | nil)
124
+ # @rbs return: RBS::MethodType | Refusal | nil
125
+ def method_type: (Class klass, Skyward::API::Endpoints::Route route, Skyward::Core::Types::Reader reader) -> (RBS::MethodType | Refusal | nil)
126
+
127
+ # Only the class's own methods, so that a method it inherits, as from
128
+ # Skyward::API or Kernel, is never suggested.
129
+ # @rbs klass: Class
130
+ # @rbs to: Symbol
131
+ # @rbs return: String?
132
+ def unrouted: (Class klass, Symbol to) -> String?
87
133
 
88
134
  # @rbs owner: Module
89
135
  # @rbs name: Symbol
@@ -91,10 +137,10 @@ module Skyward::API::Assembly::Boot
91
137
  # @rbs return: RBS::MethodType?
92
138
  def signature: (Module owner, Symbol name, Skyward::Core::Types::Reader reader) -> RBS::MethodType?
93
139
 
94
- # @rbs parameters: Method::param_types
140
+ # @rbs method: UnboundMethod
95
141
  # @rbs type: RBS::Types::function?
96
- # @rbs return: Array[[Symbol, bool, RBS::Types::t]] | String
97
- def signed: (Method::param_types parameters, RBS::Types::function? type) -> (Array[[ Symbol, bool, RBS::Types::t ]] | String)
142
+ # @rbs return: Array[[Symbol, bool, RBS::Types::t]] | Refusal
143
+ def signed: (UnboundMethod method, RBS::Types::function? type) -> (Array[[ Symbol, bool, RBS::Types::t ]] | Refusal)
98
144
 
99
145
  # @rbs method_type: RBS::MethodType
100
146
  # @rbs return: String
@@ -106,8 +152,8 @@ module Skyward::API::Assembly::Boot
106
152
 
107
153
  # @rbs keywords: Hash[Symbol, bool]
108
154
  # @rbs function: RBS::Types::function
109
- # @rbs return: String
110
- def stale: (Hash[Symbol, bool] keywords, RBS::Types::function function) -> String
155
+ # @rbs return: Refusal
156
+ def stale: (Hash[Symbol, bool] keywords, RBS::Types::function function) -> Refusal
111
157
 
112
158
  # @rbs function: RBS::Types::function
113
159
  # @rbs return: RBS::Types::Function?
@@ -117,14 +163,38 @@ module Skyward::API::Assembly::Boot
117
163
  # @rbs return: Hash[Symbol, bool]
118
164
  def keyword_requirements: (RBS::Types::Function function) -> Hash[Symbol, bool]
119
165
 
166
+ # @rbs route: Skyward::API::Endpoints::Route
167
+ # @rbs method: UnboundMethod
168
+ # @rbs parameter: Symbol
169
+ # @rbs query: Array[Symbol]
170
+ # @rbs return: Refusal
171
+ def no_keyword: (Skyward::API::Endpoints::Route route, UnboundMethod method, Symbol parameter, Array[Symbol] query) -> Refusal
172
+
173
+ # A nested resource's renamed parameter, as `todo_id:` for `/:id`, isn't a
174
+ # misspelling DidYouMean would find, so a keyword that ends in the parameter,
175
+ # or that the parameter ends in, is meant too, when it's the only one.
176
+ # @rbs parameter: Symbol
177
+ # @rbs query: Array[Symbol]
178
+ # @rbs return: Symbol?
179
+ def meant: (Symbol parameter, Array[Symbol] query) -> Symbol?
180
+
181
+ # Core's spot of a parameter list that runs onto another line stops at the end
182
+ # of its first, so only a list written whole on the `def` line is rewritten.
183
+ # @rbs method: UnboundMethod
184
+ # @rbs parameters: Skyward::Core::Diagnostics::Spot
185
+ # @rbs keyword: Skyward::Core::Diagnostics::Spot
186
+ # @rbs parameter: Symbol
187
+ # @rbs return: String?
188
+ def rename_hint: (UnboundMethod method, Skyward::Core::Diagnostics::Spot parameters, Skyward::Core::Diagnostics::Spot keyword, Symbol parameter) -> String?
189
+
120
190
  # @rbs name: Symbol
121
191
  # @rbs required: bool
122
192
  # @rbs type: RBS::Types::t
123
193
  # @rbs pattern: Array[String | Symbol]
124
194
  # @rbs providers: Hash[Symbol, Skyward::API::Routing::Router::Provider]
125
195
  # @rbs reader: Skyward::Core::Types::Reader
126
- # @rbs return: Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | String
127
- def keyword: (Symbol name, bool required, RBS::Types::t type, Array[String | Symbol] pattern, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader) -> (Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | String)
196
+ # @rbs return: Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | Refusal
197
+ def keyword: (Symbol name, bool required, RBS::Types::t type, Array[String | Symbol] pattern, Hash[Symbol, Skyward::API::Routing::Router::Provider] providers, Skyward::Core::Types::Reader reader) -> (Skyward::API::Routing::Router::Keyword | Skyward::API::Routing::Router::Provider | Refusal)
128
198
 
129
199
  # @rbs name: Symbol
130
200
  # @rbs pattern: Array[String | Symbol]
@@ -133,16 +203,16 @@ module Skyward::API::Assembly::Boot
133
203
 
134
204
  # @rbs required: bool
135
205
  # @rbs type: RBS::Types::t
136
- # @rbs return: Skyward::API::Routing::Router::Keyword | String
137
- def request: (bool required, RBS::Types::t type) -> (Skyward::API::Routing::Router::Keyword | String)
206
+ # @rbs return: Skyward::API::Routing::Router::Keyword | Refusal
207
+ def request: (bool required, RBS::Types::t type) -> (Skyward::API::Routing::Router::Keyword | Refusal)
138
208
 
139
209
  # A provided keyword's type is the provider's to give, so it's compared, never
140
210
  # read, except that an untyped keyword is left unchecked, as untyped code is.
141
211
  # @rbs name: Symbol
142
212
  # @rbs type: RBS::Types::t
143
213
  # @rbs provider: Skyward::API::Routing::Router::Provider
144
- # @rbs return: Skyward::API::Routing::Router::Provider | String
145
- def provided: (Symbol name, RBS::Types::t type, Skyward::API::Routing::Router::Provider provider) -> (Skyward::API::Routing::Router::Provider | String)
214
+ # @rbs return: Skyward::API::Routing::Router::Provider | Refusal
215
+ def provided: (Symbol name, RBS::Types::t type, Skyward::API::Routing::Router::Provider provider) -> (Skyward::API::Routing::Router::Provider | Refusal)
146
216
 
147
217
  # @rbs type: RBS::Types::t
148
218
  # @rbs return: bool
@@ -157,8 +227,8 @@ module Skyward::API::Assembly::Boot
157
227
  # @rbs name: Symbol
158
228
  # @rbs source: :path | :query | :body | :request
159
229
  # @rbs type: Skyward::Core::Types::t
160
- # @rbs return: String?
161
- def carried: (Symbol name, :path | :query | :body | :request source, Skyward::Core::Types::t type) -> String?
230
+ # @rbs return: Refusal?
231
+ def carried: (Symbol name, :path | :query | :body | :request source, Skyward::Core::Types::t type) -> Refusal?
162
232
 
163
233
  # @rbs type: Skyward::Core::Types::t
164
234
  # @rbs within: :path | :query | :array
@@ -168,8 +238,8 @@ module Skyward::API::Assembly::Boot
168
238
  # Response values are found in the signature, because the reader can't read them.
169
239
  # @rbs type: RBS::Types::t
170
240
  # @rbs reader: Skyward::Core::Types::Reader
171
- # @rbs return: Array[Skyward::API::Routing::Router::returned] | String
172
- def returns: (RBS::Types::t type, Skyward::Core::Types::Reader reader) -> (Array[Skyward::API::Routing::Router::returned] | String)
241
+ # @rbs return: Array[Skyward::API::Routing::Router::returned] | Refusal
242
+ def returns: (RBS::Types::t type, Skyward::Core::Types::Reader reader) -> (Array[Skyward::API::Routing::Router::returned] | Refusal)
173
243
 
174
244
  # @rbs type: RBS::Types::t
175
245
  # @rbs return: Array[RBS::Types::t]
@@ -208,8 +278,8 @@ module Skyward::API::Assembly::Boot
208
278
 
209
279
  # @rbs subject: String
210
280
  # @rbs type: Skyward::Core::Types::Unreadable
211
- # @rbs return: String
212
- def unreadable: (String subject, Skyward::Core::Types::Unreadable type) -> String
281
+ # @rbs return: Refusal
282
+ def unreadable: (String subject, Skyward::Core::Types::Unreadable type) -> Refusal
213
283
 
214
284
  # @rbs text: String
215
285
  # @rbs return: String
@@ -14,11 +14,15 @@ module Skyward::API::Endpoints
14
14
 
15
15
  attr_reader description(): String?
16
16
 
17
- def self.new: (Symbol verb, String path, Symbol to, String? summary, String? description) -> instance
18
- | (verb: Symbol, path: String, to: Symbol, summary: String?, description: String?) -> instance
17
+ attr_reader file(): String?
19
18
 
20
- def self.members: () -> [ :verb, :path, :to, :summary, :description ]
19
+ attr_reader line(): Integer?
21
20
 
22
- def members: () -> [ :verb, :path, :to, :summary, :description ]
21
+ def self.new: (Symbol verb, String path, Symbol to, String? summary, String? description, String? file, Integer? line) -> instance
22
+ | (verb: Symbol, path: String, to: Symbol, summary: String?, description: String?, file: String?, line: Integer?) -> instance
23
+
24
+ def self.members: () -> [ :verb, :path, :to, :summary, :description, :file, :line ]
25
+
26
+ def members: () -> [ :verb, :path, :to, :summary, :description, :file, :line ]
23
27
  end
24
28
  end
@@ -57,10 +57,15 @@ module Skyward::API::Inputs::Coercer
57
57
  # none of them.
58
58
  MISFIT: Invalid
59
59
 
60
- # INTEGER, DATE and TIME match a String's bytes, because a path parameter
61
- # can be any bytes, and Regexp#match raises on a String that isn't UTF-8.
60
+ # INTEGER, DECIMAL, DATE and TIME match a String's bytes, because a path
61
+ # parameter can be any bytes, and Regexp#match raises on a String that isn't
62
+ # UTF-8.
62
63
  INTEGER: Regexp
63
64
 
65
+ # No exponent, NaN or Infinity: "1e1000000000" is short, but written without
66
+ # an exponent it's a billion digits long.
67
+ DECIMAL: Regexp
68
+
64
69
  BOOLEANS: Hash[String, bool]
65
70
 
66
71
  DATE: Regexp
@@ -72,6 +77,10 @@ module Skyward::API::Inputs::Coercer
72
77
 
73
78
  FORMATS: Hash[Skyward::Core::Types::scalar, String]
74
79
 
80
+ # A Hash[String, T] says its keys are Strings, so an untyped value it holds
81
+ # keeps the JSON's String keys at every level.
82
+ AS_PARSED: Array[Skyward::Core::Types::t]
83
+
75
84
  # Path and query values are Strings, so with strings: true a coercer parses them.
76
85
  # @rbs type: Skyward::Core::Types::t
77
86
  # @rbs strings: bool
@@ -122,6 +131,9 @@ module Skyward::API::Inputs::Coercer
122
131
  # @rbs return: String?
123
132
  def last: (String | Array[String] raw) -> String?
124
133
 
134
+ # @rbs return: coercer
135
+ def as_parsed: () -> coercer
136
+
125
137
  # @rbs raw: untyped
126
138
  # @rbs return: untyped
127
139
  def symbolized: (untyped raw) -> untyped
@@ -149,6 +161,12 @@ module Skyward::API::Inputs::Coercer
149
161
  # @rbs return: Ok?
150
162
  def time: (untyped raw) -> Ok?
151
163
 
164
+ # A JSON number isn't one, because JSON.parse has already made it a Float,
165
+ # which may have lost digits.
166
+ # @rbs raw: untyped
167
+ # @rbs return: Ok?
168
+ def decimal: (untyped raw) -> Ok?
169
+
152
170
  # @rbs value: Skyward::Core::Types::literal
153
171
  # @rbs strings: bool
154
172
  # @rbs expected: String?
@@ -104,6 +104,12 @@ module Skyward::API::Serializer::Writers
104
104
  # @rbs return: String
105
105
  def time: (Time value) -> String
106
106
 
107
+ # A String, so a client that reads JSON numbers as doubles keeps every digit,
108
+ # and "F" so it never has an exponent.
109
+ # @rbs value: BigDecimal
110
+ # @rbs return: String
111
+ def decimal: (BigDecimal value) -> String
112
+
107
113
  # @rbs value: untyped
108
114
  # @rbs at: String
109
115
  # @rbs return: untyped
@@ -43,7 +43,7 @@ class Skyward::API::Serializer
43
43
  # @rbs return: Writers::Writer
44
44
  def compile: (Skyward::API::Routing::Router::returned member) -> Writers::Writer
45
45
 
46
- # Untyped code can return any response value.
46
+ # Untyped code can return any response value, or a Rack triple.
47
47
  # @rbs return: Writers::Writer
48
48
  def untyped: () -> Writers::Writer
49
49
 
@@ -62,6 +62,18 @@ class Skyward::API::Serializer
62
62
  # @rbs return: Writers::Writer
63
63
  def rack: () -> Writers::Writer
64
64
 
65
+ # Nothing typed says an untyped value is a triple, so it must have a status HTTP has and a body Rack can send.
66
+ # @rbs return: Writers::Writer
67
+ def untyped_rack: () -> Writers::Writer
68
+
69
+ # @rbs fits: ^(untyped) -> bool
70
+ # @rbs return: Writers::Writer
71
+ def rack_writer: (^(untyped) -> bool fits) -> Writers::Writer
72
+
73
+ # @rbs given: untyped
74
+ # @rbs return: bool
75
+ def triple?: (untyped given) -> bool
76
+
65
77
  # @rbs problem: Problem
66
78
  # @rbs given: untyped
67
79
  # @rbs return: Skyward::API::Assembly::Dispatcher::response
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: skyward-api
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jake Bottrall
@@ -15,14 +15,28 @@ dependencies:
15
15
  requirements:
16
16
  - - '='
17
17
  - !ruby/object:Gem::Version
18
- version: 0.3.0
18
+ version: 0.4.0
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
23
  - - '='
24
24
  - !ruby/object:Gem::Version
25
- version: 0.3.0
25
+ version: 0.4.0
26
+ - !ruby/object:Gem::Dependency
27
+ name: bigdecimal
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '3.1'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: '3.1'
26
40
  - !ruby/object:Gem::Dependency
27
41
  name: zeitwerk
28
42
  requirement: !ruby/object:Gem::Requirement