@alxia/core 0.1.0 → 0.2.0

package/docs/guide/routes.md

@@ -243,6 +243,7 @@ Every part is optional, and each one is any Standard Schema.
 | `cookies` | the `Cookie` header, by name | `Readonly<Record<string, string>>` |
 | `body` | the body, parsed by its `content-type` | `undefined`: read `ctx.request` yourself |
 | `response` | the body of each status the route may answer | any status, any body ([Replies](replies.md)) |
+| `bodyLimit` | not a schema: the most bytes the body may hold, a 413 past it ([Body size](#body-size-bodylimit)) | no limit beyond `listen`'s `maxRequestBodySize` |
 | `detail` | nothing at runtime: what [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi) says of the route | — |
 
 The handler reads each part as its schema's **output**: a schema that
@@ -321,7 +322,115 @@ const app = alxia()
 ```
 
 A parser that throws is a 400 with the code `unreadable_body` and the
-error's message.
+error's message. A parser that reads past the route's
+[`bodyLimit`](#body-size-bodylimit) gets a 413.
+
+### Body size: `bodyLimit`
+
+`listen`'s `maxRequestBodySize` caps every body the server takes. A route can
+cap its own body below that limit:
+
+| Where | Applies to |
+| --- | --- |
+| `bodyLimit` in a route's schema | that route, whatever `bodyLimit()` was called before it |
+| `app.bodyLimit(bytes)` | every route declared after it on the app, a group's included |
+| `group.bodyLimit(bytes)` inside a group | the group's routes declared after it, never the app's |
+| a plugin's routes, given to `use` | their own limit only: the app's `bodyLimit()` never reaches them. A `bodyLimit()` the plugin calls applies to the app's routes declared after `use`, as its hooks do |
+
+```ts
+import { alxia } from '@alxia/core';
+import { z } from 'zod';
+
+const Note = z.object({ text: z.string() });
+
+const app = alxia()
+	.bodyLimit(64 * 1024) // the app's default: 64 KiB
+	.post('/notes', { body: Note }, ({ body, reply }) => reply(201, body))
+	.group('/import', (bulk) =>
+		bulk
+			.bodyLimit(4 * 1024 * 1024) // this group only: 4 MiB
+			.post('/notes', { body: z.array(Note) }, ({ body, reply }) => reply(200, body.length)),
+	)
+	.post(
+		'/upload',
+		{ bodyLimit: 25 * 1024 * 1024 }, // this route only: 25 MiB
+		async ({ request, reply }) => {
+			let bytes = 0;
+			for await (const chunk of request.body ?? []) bytes += chunk.byteLength;
+			return reply(200, bytes);
+		},
+	);
+```
+
+The limit is a whole number of bytes, 0 or more. Any other value throws a
+`TypeError` when the route is declared:
+`POST /upload: bodyLimit must be a whole number of bytes, 0 or more; got -1`.
+
+How a body is held to it, without reading it whole:
+
+1. **`Content-Length` first.** A declared length over the limit is refused
+   without reading a byte.
+2. **Then a count.** Without a `Content-Length`, as with a chunked upload,
+   or with a false one, the bytes are counted as they arrive. The read fails
+   at the first chunk that passes the limit and the rest is never pulled. A
+   body of exactly `bodyLimit` bytes is read.
+
+The count covers every reader of the body. That means the built-in JSON,
+form and text parsers, a [`parser`](#body-parsers) of the app's, a route
+hook (`derive`, `wrap`), and a handler that reads `ctx.request.body` as a stream, as `/upload` does
+above. That handler sees a stream like any other, and the stream fails once
+the count passes the limit. Measured on a 25 MiB limit through `listen`,
+with 256 MiB offered: the handler read 25 MiB, the client had sent about
+25.3 MiB when the request was refused, and the process grew by about 2 MiB.
+[`body-limit.spec.ts`](https://github.com/softistx/alxia/blob/develop/packages/core/src/app/body-limit.spec.ts)
+repeats that run: it holds the read and the growth under the limit, and the
+bytes sent within 8 MiB of it.
+
+A global hook, `onRequest` or `around`, runs before the route is known, so
+it reads the body whole. If one has read it, the route's limit is skipped:
+cap such a hook with `maxRequestBodySize`.
+
+Past the limit the request is answered with a 413:
+
+```json
+{ "error": "content_too_large", "limit": 65536 }
+```
+
+Its body is the exported `ContentTooLargeBody`. The 413 is in the type of
+every route under a limit, so a typed client reads it, and
+[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi) documents
+it. A route with no limit has no default 413 in its type, and reads its
+body as it always has.
+
+What the read throws is a `ContentTooLargeError`, an `HttpError` with the
+route's `limit`. The route answers it as a refusal, as it answers a 400:
+the [`onRefusal`](hooks.md#onrefusal) hook in force reads
+`{ kind: 'body_limit', limit }` and may answer in another format, such as
+an RFC 9457 problem. The `onError` hooks never see it.
+
+```ts
+import { alxia, problem } from '@alxia/core';
+import { z } from 'zod';
+
+const api = alxia()
+	.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 }, ({ reply }) => reply(200, 'ok'));
+// a body past 10 MB → 413, application/problem+json:
+// { "type": "urn:ietf:params:jmap:error:limit", "status": 413, "limit": "maxSizeRequest" }
+```
+
+The hook's replies then take the default 413's place in the type of every
+route under a limit. A hook that returns nothing for a `body_limit` sends
+the default 413, which stays in the type beside them
+([Hooks](hooks.md#onrefusal)).
+
+A handler that streams its own response while it reads the body may have
+sent its headers before the count passes the limit. In that case its
+response stream fails instead of answering a 413.
 
 ## The 400
 
@@ -356,6 +465,11 @@ Two codes are the framework's: `invalid_json` (the body is not JSON) and
 `unreadable_body` (a parser threw). The 400 is in the type of every route
 that validates part of its request, so a client reads it.
 
+The 400 is the default. [`onRefusal`](hooks.md#onrefusal) answers a refused
+request in your own format for the routes declared after it, such as an RFC
+9457 problem sent as `application/problem+json`. Its reply then takes the
+400's place in those routes' types.
+
 ## What the types refuse
 
 The schema argument is checked against the path and against

package/docs/guide/server-sent-events.md

@@ -2,7 +2,8 @@
 
 This page covers streaming events to a client: a handler replies with an
 async iterable, each value is one event, and the client reads the same
-values back as an async iterable.
+values back as an async iterable. A stream may also name its events —
+`event: state`, `event: ping` — each with a schema of its own.
 
 ```ts
 import { alxia, eventStream } from '@alxia/core';
@@ -43,12 +44,164 @@ The handler replies with an async iterable of what `item` accepts; each
 value is validated and sent as `item`'s **output**, so an unknown key the
 schema strips never leaves the server, as for any reply.
 
-`isEventStreamSchema(schema)` tells whether a schema is one `eventStream`
-made: what a plugin documenting the app — an OpenAPI generator — reads.
+`isEventStreamSchema(schema)` tells whether a schema is one
+`eventStream(schema)` made: what a plugin documenting the app — an OpenAPI generator — reads.
+
+## Named events
+
+```ts
+function eventStream<Events extends EventSchemas>( // Readonly<Record<string, StandardSchemaV1>>
+	events: Events,
+): NamedEventStreamSchema<Events>;
+```
+
+Given a schema per event name, the stream sends each event with its
+`event:` line, as a protocol that tells its events apart by name expects —
+JMAP's push, for one, sends `state` and `ping`:
+
+```ts
+import { alxia, eventStream } from '@alxia/core';
+import { z } from 'zod';
+
+const StateChange = z.object({
+	'@type': z.literal('StateChange'),
+	changed: z.record(z.string(), z.record(z.string(), z.string())),
+});
+const Ping = z.object({ interval: z.number().int() });
+
+const Push = eventStream({ state: StateChange, ping: Ping });
+
+const app = alxia().get('/push', { response: { 200: Push } }, ({ reply }) =>
+	reply(
+		200,
+		(async function* () {
+			yield Push.event('ping', { interval: 30 });
+			yield Push.event(
+				'state',
+				{ '@type': 'StateChange', changed: { a1: { Email: 's42' } } },
+				{ id: 's42' },
+			);
+		})(),
+	),
+);
+```
+
+```text
+event: ping
+data: {"interval":30}
+
+event: state
+id: s42
+data: {"@type":"StateChange","changed":{"a1":{"Email":"s42"}}}
+
+```
+
+- **What the handler yields** is `{ event, data, id?, retry? }`: `event`
+  one of the declared names, `data` what that name's schema accepts. Any
+  other name, or data of another event, is a compile error. The data is
+  validated and sent as its schema's output, as for an unnamed stream.
+- **`Push.event(name, data, fields?)`** builds one, typed by the schema of
+  its name. A plain `{ event: 'ping', data }` object yielded from an
+  `async function*` passed to `reply(200, …)` widens `event` to `string`,
+  which the stream's type refuses; `Push.event` keeps the literal. A
+  generator annotated with the union takes plain objects too:
+
+  ```ts
+  import type { EventInput } from '@alxia/core';
+
+  async function* pings(): AsyncGenerator<EventInput<typeof Push>> {
+  	yield { event: 'ping', data: { interval: 30 } };
+  }
+  ```
+
+- **`id`** is the event's id, which an `EventSource` sends back as
+  `Last-Event-ID` when it reconnects. **`retry`**, a whole number of
+  milliseconds, tells an `EventSource` how long to wait before reconnecting.
+  Both are left out unless given.
+- **The client** reads `{ event, data, id? }`, a union discriminated by
+  `event`: see [Reading it](#reading-it).
+
+### What is refused
+
+A field holding a line break would write a frame the handler never
+yielded — `id: 1\ndata: forged` is two lines. So:
+
+| What | When | Result |
+| --- | --- | --- |
+| an event name that is empty, or holds a CR, an LF or a NUL | `eventStream({ … })` | a `TypeError`, when the app is built |
+| no event at all, or a value that is not a Standard Schema | `eventStream({ … })` | a `TypeError`, when the app is built |
+| an `id` that is not a string, or holds a CR, an LF or a NUL | the event is yielded | the stream ends with an error, before the event is written |
+| a `retry` that is not a whole number, 0 or more | the event is yielded | the stream ends with an error, before the event is written |
+| an undeclared `event`, or a value that is not `{ event, data }` | the event is yielded | the stream ends with an error, before the event is written |
+
+The types refuse each of the last three; they come from a cast or from
+JavaScript. These checks run even with `validateResponses: false`, which
+skips only the data's schema. Data is never a risk: it is JSON, whose line
+breaks are escaped, so a string holding one stays on a single `data:` line.
+
+### Pings, the end of the stream, and a client that leaves
+
+A push stream usually waits on two things at once: what it pushes, and a
+timer that pings. The handler reads `request.signal`, aborted when the
+client leaves, to stop waiting at once; its `finally` releases the timer
+and the subscription. Returning ends the stream — what a client's
+`closeafter=state` asks for:
+
+```ts
+app.get(
+	'/events',
+	{
+		query: z.object({ closeafter: z.enum(['state', 'no']).default('no') }),
+		response: { 200: Push },
+	},
+	({ query, request, reply }) =>
+		reply(
+			200,
+			(async function* () {
+				const queue: EventInput<typeof Push>[] = [];
+				let wake = () => {};
+				const timer = setInterval(() => {
+					queue.push(Push.event('ping', { interval: 30 }));
+					wake();
+				}, 30_000);
+				const subscription = changes.subscribe((change) => {
+					queue.push(Push.event('state', change));
+					wake();
+				});
+				request.signal.addEventListener('abort', () => wake());
+				try {
+					while (!request.signal.aborted) {
+						const next = queue.shift();
+						if (next === undefined) {
+							await new Promise<void>((resolve) => {
+								wake = resolve;
+							});
+							continue;
+						}
+						yield next;
+						if (next.event === 'state' && query.closeafter === 'state') return;
+					}
+				} finally {
+					clearInterval(timer); // runs when the client leaves, or the stream ends
+					subscription.close();
+				}
+			})(),
+		),
+);
+```
+
+Without the signal, a generator waiting on a promise is closed only when it
+next yields: its `finally` would wait for the next ping.
+
+`isNamedEventStreamSchema(schema)` tells whether a schema is a named
+stream, and `schema['~events']` holds its schemas by name: what an OpenAPI
+generator reads. `isEventStreamSchema` stays true of the unnamed form only.
 
 ## What is sent
 
-- Each value is one event: a `data:` line of JSON, then a blank line.
+- Each value is one event: a `data:` line of JSON, then a blank line. On
+  a named stream, its `event:` line comes first, then its `id:` and
+  `retry:` lines when it has them.
 - The response has `content-type: text/event-stream`,
   `cache-control: no-cache` and `x-accel-buffering: no`, so a proxy such as
   nginx does not buffer it.
@@ -82,6 +235,7 @@ app.get('/orders/:id/status', { response: { 200: eventStream(Status) } }, ({ par
 | --- | --- |
 | the reply is not an async iterable (the types refuse it; a cast gets past them) | `500`, before the stream starts; a `ResponseValidationError` naming `An event stream replies with an async iterable` is logged |
 | an event its schema refuses | the stream is ended with an error: `An event does not match its schema: …` is logged; the events already sent stay sent |
+| a named event whose fields would write another frame | the stream is ended with an error, which is logged: see [What is refused](#what-is-refused) |
 | the generator throws | the stream is ended with an error, which is logged |
 
 The status and headers are gone once the first event is sent, so an
@@ -127,7 +281,22 @@ if (ticks.status === 200) {
 }
 ```
 
-Any `EventSource` reads it too: each `data` is the JSON of one event.
+On a named stream, each one is `{ event, data, id? }`, a union
+discriminated by `event`, its `data` typed by that name's schema:
+
+```ts
+const push = await api.get('/push');
+if (push.status === 200) {
+	for await (const item of push.data) {
+		if (item.event === 'state') console.log(item.data.changed, item.id);
+		else console.log('ping every', item.data.interval);
+	}
+}
+```
+
+Any `EventSource` reads it too: each `data` is the JSON of one event, and a
+named event is dispatched under its name
+(`source.addEventListener('state', …)`).
 
 In a test, the body is the text of the events:
 
@@ -151,3 +320,6 @@ expect(await response.text()).toBe('data: {"n":1}\n\ndata: {"n":2}\n\n');
 
 - [Replies](replies.md#how-a-body-is-sent): how every other body is sent.
 - [WebSockets](websockets.md): when the client sends too.
+- [`@alxia/compress`](https://www.npmjs.com/package/@alxia/compress) leaves
+  an event stream alone by default; opted in with `compressible`, it
+  flushes each event as it is sent.

package/docs/guide/serving.md

@@ -33,7 +33,7 @@ a `Bun.serve` given [`websocket`](#websocket).
 | `hostname` | `string` | Bun's | the interface to listen on |
 | `development` | `boolean` | Bun's | Bun's development mode, which hot-reloads `page` bundles |
 | `idleTimeout` | `number` | Bun's | seconds before an idle connection is closed |
-| `maxRequestBodySize` | `number` | Bun's | the largest body accepted, in bytes |
+| `maxRequestBodySize` | `number` | Bun's | the largest body the server accepts, in bytes; a route's [`bodyLimit`](routes.md#body-size-bodylimit) caps its own below it |
 | `tls` | `Bun.TLSOptions` | none | serve HTTPS |
 
 ```ts

package/docs/guide/types.md

@@ -83,7 +83,9 @@ interface Outcome<Status extends number = number, Data = unknown> {
 | each reply the handler can return | it has none |
 | a redirect the handler returns | always |
 | each reply a `derive`, `wrap` or `onError` before the route can return | always |
-| `400`, `ValidationErrorBody` | the route validates a part of its request |
+| `400`, `ValidationErrorBody` | the route validates a part of its request, and no `onRefusal` hook is declared before it |
+| each reply the `onRefusal` hook before the route can return, in place of the 400 and the 413 | the route validates a part of its request, or has a `bodyLimit`; the default of each kind too when the hook may return nothing |
+| `413`, `ContentTooLargeBody` | the route has a `bodyLimit` of its own, or a `bodyLimit()` was called before it ([Routes](routes.md#body-size-bodylimit)), and no `onRefusal` hook is declared before it, or one that may return nothing |
 | `500`, `InternalErrorBody` | always |
 
 ```ts

package/docs/guide/websockets.md

@@ -46,7 +46,7 @@ The schema is required; `{}` validates nothing.
 
 | Part | Checks | Refused |
 | --- | --- | --- |
-| `params`, `query`, `headers`, `cookies` | the upgrade request, as a route's | a 400 with every issue, and no socket |
+| `params`, `query`, `headers`, `cookies` | the upgrade request, as a route's | the 400 with every issue, or the reply of the `onRefusal` hook in force ([Hooks](hooks.md#onrefusal)), and no socket |
 | `message` | each message the client sends, parsed as JSON | answered on the socket with a `ValidationErrorBody`; the socket stays open, the handler is not called |
 | `send` | each message the server sends | the message is not sent: `send` rejects with a `ResponseValidationError`, which, in a handler, closes the socket with `1011` |
 | `detail` | nothing at runtime: what OpenAPI says of it | — |

package/docs/guide/writing-a-plugin.md

@@ -17,7 +17,7 @@ hooks — are in [Groups and plugins](groups-and-plugins.md#plugins).
 An app is a plugin. What it declares is mounted on the app that uses it,
 and its types come with it:
 
-- its route hooks (`derive`, `decorate`, `wrap`, `onError`) apply to the
+- its route hooks (`derive`, `decorate`, `wrap`, `onError`, `onRefusal`) apply to the
   routes declared after `use`, and what they add is typed on them;
 - its routes are mounted under the app's prefix, behind the hooks declared
   before `use`;

package/docs/roadmap.md

@@ -11,11 +11,15 @@ Nothing scheduled yet.
 
 ## Next
 
-Nothing scheduled yet.
+- **A body too large through `onRefusal`.** A request whose body is over a
+  limit becomes a refusal of its own kind, `body_limit`, so the hook that
+  shapes the 400 can shape the 413 too, as an RFC 9457 problem with its
+  `limit`.
 
 ## Later
 
-Nothing scheduled yet.
+- **Comments on a stream.** A handler yielding a comment line of its own
+  (`: …`), beside the keep-alive the stream already sends while idle.
 
 ## Not planned
 
@@ -39,6 +43,35 @@ Nothing scheduled yet.
 
 ## Shipped
 
+### Next release
+
+- **Refusals in your format.** `onRefusal(hook)` answers a request the
+  route's schemas refuse with your own reply instead of
+  `400 { error: 'validation', issues }`, for the routes declared after it.
+  The hook reads the part that failed and every issue, and may answer 400
+  or another 4xx. Its reply takes the 400's place in each route's type, so
+  the client reads it. Given schemas, `@alxia/openapi` documents it under
+  its content type. A group's hook stays in the group, and the default is
+  unchanged.
+- **RFC 9457 problems.** `problem({ type, status, detail, … })` is a reply
+  sent as `application/problem+json`, with its extension members typed:
+  the error format of JMAP and other APIs built on problem details.
+- **Named server-sent events.** `eventStream({ state: State, ping: Ping })`
+  maps each event name to the schema of its data: the handler yields only
+  declared events, each sent with its `event:` line and, when given, its
+  `id:` and `retry:`; the client reads a union discriminated by `event`. A
+  line break in an id, or a retry that is not a whole number, is refused
+  before it can write a frame the handler never yielded.
+- **A body size per route.** `bodyLimit` on a route, or `bodyLimit(bytes)`
+  for the app or a group, caps its request body below the server's
+  `maxRequestBodySize`. A body over the limit is refused with a typed 413,
+  which `@alxia/openapi` documents. A `Content-Length` over the limit is
+  refused unread, and a chunked upload is cut off as soon as it passes the
+  limit, never buffered whole. This holds for JSON, forms, text, custom
+  parsers and a handler reading the raw stream. The refusal reaches
+  `onRefusal` as `{ kind: 'body_limit', limit }`, so a JMAP server answers
+  it with its own problem.
+
 ### 0.1.0
 
 - **Typed routes on Bun.** `alxia()` declares `get`, `post`, `put`, `patch`,