@alxia/core 0.1.0 → 0.2.0

package/docs/troubleshooting.md

@@ -20,6 +20,8 @@ a trap that prints nothing is headed by its symptom.
 - [`the plugin's … reads its context as any: annotate what it reads, or leave it unannotated`](#the-plugins--reads-its-context-as-any-annotate-what-it-reads-or-leave-it-unannotated)
 - [`… is not assignable to type 'ProvidedBy<C, …>'`](#-is-not-assignable-to-type-providedbyc-)
 - [`route() needs one method: declare the operation as const`](#route-needs-one-method-declare-the-operation-as-const)
+- [`Type 'Reply<500, …>' is not assignable to type 'MaybePromise<void | Reply<ClientErrorStatus, any> | undefined>'`](#type-reply500--is-not-assignable-to-type-maybepromisevoid--replyclienterrorstatus-any--undefined)
+- [`'500' does not exist in type 'RefusalResponses'`](#500-does-not-exist-in-type-refusalresponses)
 
 **Building the app**
 
@@ -36,12 +38,14 @@ a trap that prints nothing is headed by its symptom.
 - [`GET /… is declared twice`](#get--is-declared-twice)
 - [`GET /…: the handler is missing`](#get--the-handler-is-missing)
 - [`group(): build is missing`](#group-build-is-missing)
+- [`onRefusal(): the hook is missing`](#onrefusal-the-hook-is-missing)
 - [`page(): /… is already served`](#page--is-already-served)
 - [`GET /… is already served by a page`](#get--is-already-served-by-a-page)
 
 **Responses**
 
 - [`400 {"error":"validation","issues":[…]}`](#400-errorvalidationissues)
+- [A route still answers `{"error":"validation"}` after `onRefusal`](#a-route-still-answers-errorvalidation-after-onrefusal)
 - [`404 {"error":"not_found"}`](#404-errornot_found)
 - [`405 {"error":"method_not_allowed"}`](#405-errormethod_not_allowed)
 - [`426 {"error":"upgrade_required"}`](#426-errorupgrade_required)
@@ -57,7 +61,13 @@ a trap that prints nothing is headed by its symptom.
 - [`ResponseValidationError: … the 200 reply does not match its schema`](#responsevalidationerror--the-200-reply-does-not-match-its-schema)
 - [`ResponseValidationError: … declares no 201 reply`](#responsevalidationerror--declares-no-201-reply)
 - [`TypeError: … the handler returned no reply. Return ctx.reply(status, body).`](#typeerror--the-handler-returned-no-reply-return-ctxreplystatus-body)
+- [`TypeError: … the onRefusal hook returned neither a reply nor nothing.`](#typeerror--the-onrefusal-hook-returned-neither-a-reply-nor-nothing)
 - [`TypeError: An event does not match its schema`](#typeerror-an-event-does-not-match-its-schema)
+- [`TypeError: An event id must not hold a line break or a NUL`](#typeerror-an-event-id-must-not-hold-a-line-break-or-a-nul), and `An event id must be a string`
+- [`TypeError: An event retry must be a whole number of milliseconds, 0 or more`](#typeerror-an-event-retry-must-be-a-whole-number-of-milliseconds-0-or-more)
+- [`TypeError: The event "…" is not declared: …`](#typeerror-the-event--is-not-declared-), and `An event of a named stream is an object { event, data }`
+- [`TypeError: An event name must not hold a line break or a NUL`](#typeerror-an-event-name-must-not-hold-a-line-break-or-a-nul), and `An event name must not be empty`, `A named event stream declares at least one event`, `The event "…" is not a Standard Schema`
+- [`Type 'string' is not assignable to type '"ping"'` on a named stream](#type-string-is-not-assignable-to-type-ping-on-a-named-stream)
 
 **WebSockets**
 
@@ -123,7 +133,7 @@ error TS2561: Object literal may only specify known properties, but 'quey' does
 ```
 
 When the schema object is a variable, the message names the key instead:
-`"quey" is not a part of a route: params, query, headers, cookies, body, response or detail`.
+`"quey" is not a part of a route: params, query, headers, cookies, body, response, bodyLimit or detail`.
 A variable with no known key at all gives
 `TS2559: Type '{ quey: … }' has no properties in common with type 'RouteSchema'`.
 
@@ -131,7 +141,7 @@ A variable with no known key at all gives
 read the raw value.
 
 **Fix:** use one of `params`, `query`, `headers`, `cookies`, `body`,
-`response` or `detail`:
+`response`, `bodyLimit` or `detail`:
 
 ```ts
 app.get('/users', { query: z.object({ page: zq.int().optional() }) }, handler);
@@ -420,6 +430,65 @@ export const getPet = {
 } as const;
 ```
 
+### `Type 'Reply<500, …>' is not assignable to type 'MaybePromise<void | Reply<ClientErrorStatus, any> | undefined>'`
+
+**When:** an `onRefusal` hook returns a reply whose status is not a client
+error, such as a 500 or a 200.
+
+```text
+error TS2322: Type 'Reply<500, { readonly status: 500; }>' is not assignable to type 'MaybePromise<void | Reply<ClientErrorStatus, any> | undefined>'.
+```
+
+**Why:** a refused request is the client's error. A 5xx would tell a client
+to retry a request that will be refused again, and a 2xx would say it
+succeeded.
+
+**Fix:** answer with a 4xx, such as 400 or 422:
+
+```ts
+app.onRefusal((refusal) => problem({ status: 422, detail: `the request is refused: ${refusal.kind}` }));
+```
+
+### `Property 'part' does not exist on type 'Refusal'`
+
+**When:** an `onRefusal` hook reads `part` or `issues` without checking
+the refusal's `kind`, often by destructuring it:
+
+```text
+error TS2339: Property 'part' does not exist on type 'Refusal'.
+  Property 'part' does not exist on type 'BodyLimitRefusal'.
+```
+
+**Why:** a hook answers every kind of refusal. A `body_limit` refusal, a
+body past the route's `bodyLimit`, has a `limit` and no `part` or
+`issues`.
+
+**Fix:** check `kind` first. Return nothing for a kind you leave to its
+default:
+
+```ts
+app.onRefusal((refusal) =>
+	refusal.kind === 'validation' ? problem({ status: 400, detail: `the ${refusal.part} is invalid` }) : undefined,
+);
+```
+
+### `'500' does not exist in type 'RefusalResponses'`
+
+**When:** the schemas given to `onRefusal` declare a status that is not a
+client error.
+
+```text
+error TS2353: Object literal may only specify known properties, and '500' does not exist in type 'RefusalResponses'.
+```
+
+**Fix:** declare the 4xx the hook answers:
+
+```ts
+app.onRefusal({ response: { 400: Problem } }, (_, { reply }) =>
+	reply(400, { type: 'urn:example:invalid', status: 400, detail: 'invalid' }),
+);
+```
+
 ## Building the app
 
 These are `TypeError`s thrown when a route is declared, so the app fails at
@@ -627,6 +696,19 @@ third argument that is `undefined`.
 app.get('/a', { query: Query }, ({ query, reply }) => reply(200, query));
 ```
 
+### `POST /…: bodyLimit must be a whole number of bytes, 0 or more; got …`
+
+**When:** a route's `bodyLimit` is negative, fractional, `NaN` or
+`Infinity`. `bodyLimit()` throws the same message, prefixed
+`bodyLimit():`.
+
+**Fix:** give a byte count, or leave `bodyLimit` out for no limit beyond
+the server's:
+
+```ts
+app.post('/upload', { bodyLimit: 25 * 1024 * 1024 }, handler);
+```
+
 ### `group(): build is missing`
 
 **When:** `group('/admin')` is called without its function.
@@ -637,6 +719,19 @@ app.get('/a', { query: Query }, ({ query, reply }) => reply(200, query));
 app.group('/admin', (admin) => admin.derive(requireAdmin).get('/stats', stats));
 ```
 
+### `onRefusal(): the hook is missing`
+
+**When:** `onRefusal` is given its schemas but no hook. The types refuse
+that, so this comes from JavaScript or a cast.
+
+**Fix:** pass the hook after the schemas:
+
+```ts
+app.onRefusal({ response: { 400: Problem } }, (_, { reply }) =>
+	reply(400, { type: 'urn:example:invalid', status: 400, detail: 'invalid' }),
+);
+```
+
 ### `page(): /… is already served`
 
 **When:** `page(path, bundle)` names a path that another `page` or a
@@ -665,8 +760,8 @@ app.page('/dashboard', dashboard).get('/api/dashboard', ({ reply }) => reply(200
 ## Responses
 
 The app answers these itself. Their bodies are the exported
-`ValidationErrorBody`, `RoutingErrorBody`, `FileNotFoundBody`,
-`RangeNotSatisfiableBody` and `InternalErrorBody`.
+`ValidationErrorBody`, `ContentTooLargeBody`, `RoutingErrorBody`,
+`FileNotFoundBody`, `RangeNotSatisfiableBody` and `InternalErrorBody`.
 
 ### `400 {"error":"validation","issues":[…]}`
 
@@ -714,6 +809,86 @@ await fetch('/users', {
 [`@alxia/client`](https://www.npmjs.com/package/@alxia/client) sets the
 `content-type` for you.
 
+To answer it in another format, such as an RFC 9457 problem, declare
+[`onRefusal`](guide/hooks.md#onrefusal) before the routes.
+
+### A route still answers `{"error":"validation"}` after `onRefusal`
+
+**When:** an app declares `onRefusal`, and a refused request to one of its
+routes still gets the default 400.
+
+**Why**, by what you find:
+
+- The route is declared **before** the hook. A route hook applies to the
+  routes declared after it, never before: move the hook up the chain.
+- The hook is declared inside a `group`. A group's hooks stay inside it:
+  declare the hook on the app, before the group.
+- The hook returned nothing, `undefined`, for this refusal. Nothing means
+  the default: return a reply for every refusal you want answered.
+
+**Fix:** declare the hook first, and return a reply:
+
+```ts
+const app = alxia()
+	.onRefusal((refusal) =>
+		refusal.kind === 'validation' ? problem({ status: 400, detail: `the ${refusal.part} is invalid` }) : undefined,
+	)
+	.post('/users', { body: NewUser }, handler);
+```
+
+A body past the route's `bodyLimit` still gets the default
+`413 {"error":"content_too_large","limit":…}` from that hook, which returns nothing
+for a `body_limit`. Return a reply for it too to answer it in your format
+([`413`](#413-errorcontent_too_largelimit)).
+
+### `413 {"error":"content_too_large","limit":…}`
+
+**When:** a request's body is larger than its route's `bodyLimit`: the
+route's own, or the one a `bodyLimit(bytes)` before it set. Either its
+`Content-Length` says so, and the body is not read, or the bytes counted as
+it was read passed the limit:
+
+```json
+{ "error": "content_too_large", "limit": 65536 }
+```
+
+**Why:** `limit` is the route's limit, in bytes. The count covers every
+reader of the body: the JSON, form and text parsers, a `parser` of the
+app's, and a handler reading `ctx.request.body`. A body of exactly `limit`
+bytes is accepted.
+
+**Fix:** send a smaller body, or raise the limit for that route alone. A
+route's own `bodyLimit` wins over the default:
+
+```ts
+app
+	.bodyLimit(64 * 1024)
+	.post('/attachments', { bodyLimit: 25 * 1024 * 1024 }, async ({ request, reply }) => {
+		await Bun.write('attachment.bin', new Response(request.body));
+		return reply(204);
+	});
+```
+
+To answer in another format, such as an RFC 9457 problem, return it from
+an [`onRefusal`](guide/hooks.md#onrefusal) hook declared before the route,
+for the refusal of kind `body_limit`. The `onError` hooks never see it:
+
+```ts
+import { problem } from '@alxia/core';
+
+app
+	.onRefusal((refusal) =>
+		refusal.kind === 'body_limit'
+			? problem({ type: 'urn:ietf:params:jmap:error:limit', status: 413, limit: 'maxSizeRequest' })
+			: undefined,
+	)
+	.post('/api', { body: z.unknown(), bodyLimit: 10_000_000 }, handler);
+```
+
+A 413 with no JSON body comes from Bun itself. The body passed `listen`'s
+`maxRequestBodySize`, which applies to every route, before any route's
+`bodyLimit`.
+
 ### `404 {"error":"not_found"}`
 
 **When:** a request matches no route, or a `static` or `file` route finds
@@ -817,6 +992,28 @@ app
 Prefer a declared `reply` to `throw new HttpError(…)`: a thrown status is
 not in the route's type, so a typed client does not expect it.
 
+### A plugin's route reads a body past the app's `bodyLimit()`
+
+**When:** an app calls `bodyLimit(bytes)` and then `use(plugin)` with an
+app plugin, and a route of that plugin accepts a larger body.
+
+**Why:** an app's `bodyLimit()` reaches the routes declared on it and in
+its groups, never a plugin's. A plugin's route keeps the limit it was
+declared with, and its type with it. A plugin route with no `onRefusal` of
+its own is still answered by the app's hook. A function plugin that declares its routes on the app is
+bounded like any of them.
+
+**Fix:** give the plugin's route a `bodyLimit` of its own:
+
+```ts
+const uploads = alxia().post('/upload', { bodyLimit: 25 * 1024 * 1024 }, handler);
+const app = alxia().bodyLimit(64 * 1024).use(uploads);
+```
+
+A `bodyLimit()` the plugin calls instead also applies to the app's routes
+declared after `use`, as its hooks do. Call the app's own after `use` to
+keep it.
+
 ## Routing
 
 A trap that prints nothing: the answer comes from another route than the
@@ -861,6 +1058,9 @@ at runtime. Data from a database, `JSON.parse` or `any` gets past the types.
 **Why:** what leaves the server is the schema's output. A body the schema
 refuses is never sent, so the client never reads an undeclared shape.
 
+An `onRefusal` hook given schemas is checked the same way: the message
+names the route that was refused and the status the hook replied with.
+
 **Fix:** map the data to the schema before replying. To skip the check in
 a hot path you trust, turn it off for the app; the declared status is still
 enforced:
@@ -878,7 +1078,9 @@ ResponseValidationError: GET /u declares no 201 reply
 **When:** a route with `response` schemas replies with a status it did not
 declare. The types refuse that, so this comes from JavaScript or a cast.
 Redirects (3xx without a body) are exempt, and so is a reply returned by
-`onError` or a `derive`.
+`onError` or a `derive`. An `onRefusal` hook given schemas that replies
+with a status they do not declare fails the same way, naming the refused
+route: declare the status in the hook's `response`.
 
 **Fix:** declare the status in `response`:
 
@@ -901,6 +1103,20 @@ app.get('/users', async ({ reply }) => {
 });
 ```
 
+### `TypeError: … the onRefusal hook returned neither a reply nor nothing.`
+
+**When:** an `onRefusal` hook returns something that is neither a `Reply`
+nor `undefined`, such as a plain object or a `Response`. TypeScript
+refuses it, so this comes from JavaScript or a cast.
+
+**Fix:** return `reply(…)` or `problem(…)`, or nothing for the default:
+
+```ts
+app.onRefusal((refusal) =>
+	refusal.kind === 'validation' && refusal.part === 'body' ? problem({ status: 400, detail: 'bad body' }) : undefined,
+);
+```
+
 ### `TypeError: An event does not match its schema`
 
 ```text
@@ -908,7 +1124,8 @@ TypeError: An event does not match its schema: n: Invalid input: expected number
 ```
 
 **When:** a value yielded by an `eventStream` reply is refused by the
-event's schema. The response has already started with a 200, so the stream
+event's schema. On a named stream, the path starts with the event's name:
+`ping.interval: …`. The response has already started with a 200, so the stream
 is cut, and the client reads an error mid-stream instead of a 500.
 
 **Fix:** yield values the event's schema accepts, mapping them inside the
@@ -920,6 +1137,86 @@ reply(200, (async function* () {
 })());
 ```
 
+### `TypeError: An event id must not hold a line break or a NUL`
+
+```text
+TypeError: An event id must not hold a line break or a NUL: "1\ndata: forged"
+```
+
+**When:** an event yielded on a named `eventStream({ … })` has an `id`
+holding a CR, an LF or a NUL (`An event id must be a string` when it is
+not a string at all). Its type is `string`, so this comes from data
+that reached the id unchecked: a client's input, a database row.
+
+**Why:** a line break would end the `id:` line and start a field the
+handler never yielded, and an `EventSource` ignores an id holding a NUL. The
+stream ends before the event is written; the events already sent stay sent.
+
+**Fix:** make the id from something without line breaks — a counter, a
+state string you issue — or encode it:
+
+```ts
+yield Push.event('state', change, { id: encodeURIComponent(state) });
+```
+
+### `TypeError: An event retry must be a whole number of milliseconds, 0 or more`
+
+**When:** an event's `retry` is a fraction, negative, `NaN` or not a number.
+
+**Why:** an `EventSource` reads `retry:` as ASCII digits only, and ignores
+anything else; the stream ends rather than send a field no client reads.
+
+**Fix:** round it:
+
+```ts
+yield Push.event('ping', { interval: 30 }, { retry: Math.round(seconds * 1000) });
+```
+
+### `TypeError: The event "…" is not declared: …`
+
+**When:** a value yielded on a named stream has an `event` that is not one
+of the names its `eventStream({ … })` declares. The types refuse it, so this
+comes from a cast or from JavaScript. `TypeError: An event of a named stream
+is an object { event, data }` is its sibling, for a value that has no
+`event` at all.
+
+**Fix:** declare the event, or yield one that is:
+
+```ts
+const Push = eventStream({ state: StateChange, ping: Ping });
+yield Push.event('ping', { interval: 30 });
+```
+
+### `TypeError: An event name must not hold a line break or a NUL`
+
+**When:** `eventStream({ … })` is given a name holding a CR, an LF or a
+NUL, or an empty one (`An event name must not be empty`). It throws when the
+app is built, as do `A named event stream declares at least one event` and
+`The event "…" is not a Standard Schema`.
+
+**Fix:** name each event with a single line, and give each a schema:
+
+```ts
+const Push = eventStream({ state: StateChange, ping: Ping });
+```
+
+### `Type 'string' is not assignable to type '"ping"'` on a named stream
+
+**When:** a generator handed to `reply(200, …)` yields a plain
+`{ event: 'ping', data }` object: TypeScript widens its `event` to `string`,
+which no declared name is.
+
+**Fix:** build the event with the stream's `event`, which keeps the name,
+or annotate the generator:
+
+```ts
+yield Push.event('ping', { interval: 30 });
+// or
+async function* pings(): AsyncGenerator<EventInput<typeof Push>> {
+	yield { event: 'ping', data: { interval: 30 } };
+}
+```
+
 ## WebSockets
 
 ### `{"error":"validation", … "code":"invalid_json","message":"The message is not valid JSON"}`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/core",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "A zero-dependency, type-safe HTTP framework for Bun: routes validated with any Standard Schema, typed from the request to the client",
 	"license": "MIT",
 	"type": "module",