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 +4 -4
- data/README.md +12 -8
- data/lib/skyward/api/assembly/boot.rb +214 -66
- data/lib/skyward/api/endpoints/declarations.rb +5 -1
- data/lib/skyward/api/endpoints/route.rb +3 -1
- data/lib/skyward/api/inputs/coercer.rb +37 -4
- data/lib/skyward/api/openapi.rb +2 -0
- data/lib/skyward/api/serializer/writers.rb +11 -0
- data/lib/skyward/api/serializer.rb +25 -7
- data/lib/skyward/api/version.rb +1 -1
- data/lib/skyward/api.rb +1 -0
- data/sig/generated/skyward/api/assembly/boot.rbs +99 -29
- data/sig/generated/skyward/api/endpoints/route.rbs +8 -4
- data/sig/generated/skyward/api/inputs/coercer.rbs +20 -2
- data/sig/generated/skyward/api/serializer/writers.rbs +6 -0
- data/sig/generated/skyward/api/serializer.rbs +13 -1
- metadata +17 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e72e644d6adbeff511700cdcc2197311da17c48b90100c21842aad90da0ab109
|
|
4
|
+
data.tar.gz: 5b39f4e0d513aeca35ded649fddaf796aa5026a563d84649b692d9d3d6079003
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
|
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:`.
|
|
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,
|
|
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
|
|
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 `
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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:
|
|
129
|
-
def shadowing(verb, pattern, built)
|
|
130
|
-
|
|
131
|
-
return unless
|
|
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
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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 |
|
|
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
|
|
162
|
-
return method_type if method_type.is_a?(
|
|
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(
|
|
166
|
-
return signed if signed.is_a?(
|
|
218
|
+
signed = signed(method, function)
|
|
219
|
+
return signed if signed.is_a?(Refusal)
|
|
167
220
|
|
|
168
|
-
|
|
221
|
+
path_parameters = pattern.grep(Symbol) #: Array[Symbol]
|
|
222
|
+
unnamed = path_parameters.find { |name| signed.none? { |keyword, _, _| keyword == name } }
|
|
169
223
|
if unnamed
|
|
170
|
-
|
|
171
|
-
|
|
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 =
|
|
228
|
+
both = path_parameters.find { |name| providers.key?(name) }
|
|
175
229
|
if both
|
|
176
|
-
|
|
177
|
-
|
|
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.
|
|
181
|
-
problem = read.find { |keyword| keyword.is_a?(
|
|
182
|
-
|
|
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
|
-
|
|
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
|
|
276
|
+
# @rbs route: Skyward::API::Endpoints::Route
|
|
215
277
|
# @rbs reader: Skyward::Core::Types::Reader
|
|
216
|
-
# @rbs return: RBS::MethodType |
|
|
217
|
-
def method_type(klass,
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
-
|
|
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
|
|
315
|
+
# @rbs method: UnboundMethod
|
|
235
316
|
# @rbs type: RBS::Types::function?
|
|
236
|
-
# @rbs return: Array[[Symbol, bool, RBS::Types::t]] |
|
|
237
|
-
def signed(
|
|
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
|
|
240
|
-
|
|
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:
|
|
356
|
+
# @rbs return: Refusal
|
|
272
357
|
def stale(keywords, function)
|
|
273
358
|
taken = keywords.map { |name, required| "#{"?" unless required}#{name}:" }
|
|
274
|
-
|
|
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 |
|
|
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 |
|
|
470
|
+
# @rbs return: Skyward::API::Routing::Router::Keyword | Refusal
|
|
336
471
|
def request(required, type)
|
|
337
472
|
unless [REQUEST, ANY].include?(type)
|
|
338
|
-
return
|
|
339
|
-
|
|
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 |
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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] |
|
|
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
|
-
|
|
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:
|
|
668
|
+
# @rbs return: Refusal
|
|
525
669
|
def unreadable(subject, type)
|
|
526
|
-
|
|
527
|
-
|
|
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
|
|
@@ -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
|
|
42
|
-
# can be any bytes, and Regexp#match raises on a String that isn't
|
|
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 = {
|
|
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
|
|
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
|
data/lib/skyward/api/openapi.rb
CHANGED
|
@@ -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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
data/lib/skyward/api/version.rb
CHANGED
data/lib/skyward/api.rb
CHANGED
|
@@ -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
|
|
48
|
-
|
|
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:
|
|
63
|
-
def shadowing: (String verb, Array[String | Symbol] pattern, Array[Skyward::API::Routing::Router::Endpoint] built) ->
|
|
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 |
|
|
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 |
|
|
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
|
|
122
|
+
# @rbs route: Skyward::API::Endpoints::Route
|
|
84
123
|
# @rbs reader: Skyward::Core::Types::Reader
|
|
85
|
-
# @rbs return: RBS::MethodType |
|
|
86
|
-
def method_type: (Class klass,
|
|
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
|
|
140
|
+
# @rbs method: UnboundMethod
|
|
95
141
|
# @rbs type: RBS::Types::function?
|
|
96
|
-
# @rbs return: Array[[Symbol, bool, RBS::Types::t]] |
|
|
97
|
-
def signed: (
|
|
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:
|
|
110
|
-
def stale: (Hash[Symbol, bool] keywords, RBS::Types::function function) ->
|
|
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 |
|
|
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 |
|
|
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 |
|
|
137
|
-
def request: (bool required, RBS::Types::t type) -> (Skyward::API::Routing::Router::Keyword |
|
|
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 |
|
|
145
|
-
def provided: (Symbol name, RBS::Types::t type, Skyward::API::Routing::Router::Provider provider) -> (Skyward::API::Routing::Router::Provider |
|
|
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:
|
|
161
|
-
def carried: (Symbol name, :path | :query | :body | :request source, Skyward::Core::Types::t type) ->
|
|
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] |
|
|
172
|
-
def returns: (RBS::Types::t type, Skyward::Core::Types::Reader reader) -> (Array[Skyward::API::Routing::Router::returned] |
|
|
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:
|
|
212
|
-
def unreadable: (String subject, Skyward::Core::Types::Unreadable type) ->
|
|
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
|
-
|
|
18
|
-
| (verb: Symbol, path: String, to: Symbol, summary: String?, description: String?) -> instance
|
|
17
|
+
attr_reader file(): String?
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
attr_reader line(): Integer?
|
|
21
20
|
|
|
22
|
-
def
|
|
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
|
|
61
|
-
# can be any bytes, and Regexp#match raises on a String that isn't
|
|
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.
|
|
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.
|
|
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.
|
|
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
|