@znight/http 0.1.2 → 0.1.4

package/README.md

@@ -1222,8 +1222,18 @@ export class AdminController {
 HttpPlugin.configure({ guards: [AuthGuard] })
 ```
 
-`decorator.get(ctx)` reads the route metadata (`ctx.route.meta`) with its type. Guards,
-interceptors and mappers are providers: they may be request-scoped (resolved per request) and have
+`decorator.get(ctx)` reads the route metadata (`ctx.route.meta`) with its type. It accepts any
+`RouteMetaCarrier` (`{ route?: { meta } }`), not only an `HttpContext`: the contexts of other
+transports that reuse route decorators (a GraphQL resolver, a WebSocket gateway) expose their
+effective metadata the same way, so one guard helper serves every transport:
+
+```ts
+import type { RouteMetaCarrier } from '@znight/http'
+
+const isPublic = (ctx: RouteMetaCarrier): boolean => Public.get(ctx) === true
+```
+
+Guards, interceptors and mappers are providers: they may be request-scoped (resolved per request) and have
 dependencies. Plugin options also accept instances (`guards: [new IpAllowList(['10.0.0.0/8'])]`).
 
 ## Route decisions
@@ -1493,6 +1503,16 @@ app.hooks.wrap('http:request', async (event, next) => {
 stream, `run` resolves when the stream opens (`status: 200`): durations measure the time to open.
 A stream-lifetime hook is not provided.
 
+When CORS is off, routes (other than `@All`) without guards, interceptors, `@Sse`, `@Res()` or
+`@Header` take a fast lane: the plugin decides at boot what the pipeline would do for them, runs a
+synchronous handler without creating a promise and builds the headers of a JSON reply from a
+template. The replies are the same as through the full pipeline (a thrown error, an `HttpResponse`
+or anything unusual continues there, in the same request scope; a promise is awaited first). The
+lane runs the `http:request` hooks too: listeners keep it synchronous, and wrappers (such as those of
+`@znight/observability`) see the same event, in the same request scope and async context, as with
+the full pipeline; a reply whose wrappers added response headers or cookies is completed like any
+other.
+
 ## Plugin options
 
 `HttpPlugin.configure(options)` — `options` may also be a function of the container, evaluated
@@ -1579,6 +1599,7 @@ export class StatusPlugin implements Plugin, PluginHttpRoutes {
         handler: ctx => ({ up: true }), // (ctx: HttpContext) => result, serialised like a controller result
         meta: [Public.meta()], // route metadata: read by guards, checked by the route decision check
         guards: [], // extra guards (classes or instances)
+        bodyLimit: '100kb', // optional: this route's body limit, instead of the HttpPlugin bodyLimit
       },
     ]
   }
@@ -1591,9 +1612,12 @@ export class StatusPlugin implements Plugin, PluginHttpRoutes {
   then the route `guards`, the handler and the exception mappers. Global interceptors do not wrap
   plugin routes (a response envelope would break a document). The body is read lazily
   (`ctx.parseBody()`). `GET` routes answer `HEAD`; `ALL` works as for controllers.
+- `bodyLimit` (a `ByteSize`: `1048576`, `'100kb'`, `Infinity`, the grammar of the plugin option)
+  replaces the `HttpPlugin` `bodyLimit` for that route only, lower or higher, like `@BodyLimit` on a
+  controller route: reading a larger body answers 413. Without it, the plugin limit applies.
 - `meta` entries (`decorator.meta(value)`, one per group) are the route metadata. A required group
   needs a decision there too: without one the boot fails (ZNIGHT023), with a hint naming the plugin.
-- An invalid route (method, path grammar, name, handler, meta) or a collision with another route is
+- An invalid route (method, path grammar, name, handler, meta, body limit) or a collision with another route is
   ZNIGHT007 naming the plugin. `HttpPlugin.routes` lists the routes with `source: '<plugin name>'`.
 
 ## Adapters
@@ -1638,8 +1662,18 @@ HttpPlugin.configure({ adapter: fastifyAdapter({ instance }) })
 
 Znight routes are registered in an encapsulated context with their own body handling and 404
 handler, so your other routes keep Fastify's parsers. A `content-type` Fastify cannot parse (`foo`,
-an empty one) is hidden from Fastify for Znight routes, which then answer like on the other adapters
-instead of Fastify's `415`. Created instances use
+an empty one) never reaches Fastify's parsers for Znight routes, which then answer like on the other
+adapters instead of Fastify's `415`.
+
+Znight parses bodies itself, so a Znight route that no other hook needs is served straight from the
+`onRequest` hook of its context: Fastify skips its content type parsing and the steps before the
+handler, and a text reply is written on the raw response exactly as `reply.send()` writes it. Your
+hooks always run: with a `preParsing`, `preValidation` or `preHandler` hook (or an `onRoute` hook
+wrapping the handler, a schema, a subscriber of the `fastify.request.handler` tracing channel), the
+request goes through Fastify's whole lifecycle; with an `onSend` or `onResponse` hook, or headers
+and trailers set by an `onRequest` hook, the reply goes through `reply.send()`. The adapter reads
+these hooks on Fastify's internal route and reply state: should a Fastify release change it, every
+request goes through the lifecycle (slower, same responses). Created instances use
 `exposeHeadRoutes: false` (Znight serves HEAD), a `maxParamLength` of 8 KiB and a
 `frameworkErrors` handler rendering Znight errors (with your own instance, malformed URLs are
 answered by Fastify). `inject()` uses `fastify.inject()`. Event streams are sent through
@@ -1695,10 +1729,13 @@ handler returning its own `Response`.
 | `serveOptions` | Options of `Bun.serve()` (`tls`, `idleTimeout`, `development`, `error`...; Znight sets `port`, `hostname`, `fetch`). Bun only |
 
 On Bun, the body limits are Znight's (`bodyLimit`, `@BodyLimit`): `maxRequestBodySize` defaults to
-unlimited instead of Bun's 128 MiB. Bun's `idleTimeout` (10 s by default) still closes idle
+unlimited instead of Bun's 128 MiB. A body with a `Content-Length` is read at once
+(`request.bytes()`, refused with 413 before reading when the length is above the limit), a chunked
+one as a stream (413 as soon as it passes the limit). Bun's `idleTimeout` (10 s by default) still closes idle
 connections and stalled requests, but is lifted while a streamed response is sent (SSE, slow
 producers), then restored. In your own `Bun.serve({ fetch: adapter.fetch })` the adapter cannot
-lift it: keep the SSE `heartbeat` below `idleTimeout` (the 8 s default does).
+lift it: keep the SSE `heartbeat` below `idleTimeout` (the 8 s default does). Bun checks idle timeouts
+every 4 seconds, so an `idleTimeout` of 4 s or less closes a connection even while it is written to.
 
 `Bun.serve()` sends streamed bodies with chunked transfer encoding even when a `Content-Length`
 header is set (unless the whole stream is available at once): files sent with
@@ -2084,7 +2121,8 @@ Rules:
   boot.
 - `@Validate(S)` applies `S` to the `@Body()` parameter (`@Validate(S)` + `@Body()` ≡ `@Body(S)`);
   `@Validate(S)` + `@Body(S2)` is ZNIGHT005. Without a `@Body()` parameter the body is still
-  validated (and discarded): `invoke: async (c, ctx) => { await validate(S, await ctx.parseBody(), 'body'); return c.m() }`.
+  validated (and discarded): `invoke: async (c, ctx) => { await validate(S, await ctx.parseBody(), 'body'); return c.m() }`
+  (this `async` arrow `await`s its other validations too).
 - The plugin parses the body before the interceptors when `params` contains a `source: 'body'`
   entry or `uploads` is not empty; `ctx.body` is `undefined` otherwise (generated code then uses
   `await ctx.parseBody()`).
@@ -2117,31 +2155,53 @@ Rules:
 
 ### `invoke` generation
 
-`invoke(controller, ctx)` extracts every argument in parameter order and calls the handler. It is
-`async` and `await`s every `validate()` call when the route has at least one schema; otherwise it
-is synchronous. It returns the handler result as is (promises included).
-
-| Parameter                               | Generated expression                                                           |
-| --------------------------------------- | ------------------------------------------------------------------------------ |
-| `@Param('id') id: T`                    | `coerce.X(ctx.params['id'], 'param "id"')` (see below)                         |
-| `@Param('id', S)`                       | `await validate(S, ctx.params['id'], 'param "id"')`                            |
-| `@Param()`                              | `ctx.params as never` · with schema: `await validate(S, ctx.params, 'params')` |
-| `@Query('page') page: T`                | `coerce.X(ctx.query['page'], 'query "page"')`                                  |
-| `@Query('page', S)`                     | `await validate(S, ctx.query['page'], 'query "page"')`                         |
-| `@Query()` / `@Query(S)`                | `ctx.query as never` / `await validate(S, ctx.query, 'query')`                 |
-| `@Body()` / `@Body(S)` / `@Validate(S)` | `ctx.body as never` / `await validate(S, ctx.body, 'body')`                    |
-| `@Headers('X-Api-Key') key: T`          | `coerce.X(ctx.headers['x-api-key'], 'header "x-api-key"')` (name lower-cased)  |
-| `@Headers()`                            | `ctx.headers as never`                                                         |
-| `@Cookie('sid') sid: T`                 | `coerce.X(ctx.cookies['sid'], 'cookie "sid"')` (or `coerce.optional(...)`)     |
-| `@Cookie('sid', S)`                     | `await validate(S, ctx.cookies['sid'], 'cookie "sid"')`                        |
-| `@Cookie()` / `@Cookie(S)`              | `ctx.cookies as never` / `await validate(S, ctx.cookies, 'cookies')`           |
-| `@SignedCookie('sid') sid: T`           | `coerce.X(ctx.signedCookie('sid'), 'cookie "sid"')`                            |
-| `@SignedCookie('sid', S)`               | `await validate(S, ctx.signedCookie('sid'), 'cookie "sid"')`                   |
-| `@Req()` / `@Res()`                     | `ctx.request as never` / `ctx.response as never` (+ `rawResponse: true`)       |
-| `@UploadedFile('f') f: File`            | `uploads.file(ctx, 'f')` · optional: `uploads.optionalFile(ctx, 'f')`          |
-| `@UploadedFiles('f') f: File[]`         | `uploads.files(ctx, 'f')` · optional: `uploads.optionalFiles(ctx, 'f')`        |
-| `@UploadedFile()` / `@UploadedFiles()`  | the same helpers with `undefined` as field (any field)                         |
-| `@Ctx()`                                | `ctx`                                                                          |
+`invoke(controller, ctx)` extracts every argument in parameter order and calls the handler. It
+returns the handler result as is (promises included); the plugin awaits it only when it is a
+thenable. Without schema it is a synchronous arrow:
+`(c: UserController, ctx: HttpContext) => c.find(coerce.number(ctx.params['id'], 'param "id"'))`.
+
+With schemas it stays synchronous as long as every `validate()` returns a value (Zod, Valibot or
+ArkType schemas without async refinements): no promise, no `await` per request. The arguments up to
+the last validated one are evaluated in order into `a<index>` constants (`@Ctx()` stays `ctx`), the
+later ones are inlined in the call, and each validated argument is followed by a fallback for
+asynchronous schemas:
+
+```ts
+invoke: (c: UserController, ctx: HttpContext) => {
+  const a0 = coerce.number(ctx.params['id'], 'param "id"')
+  const a1 = validate(UpdateUser, ctx.body, 'body')
+  if (isThenable(a1)) return (async () => c.update(a0, await a1, ctx))()
+  return c.update(a0, a1, ctx)
+},
+```
+
+When `validate()` returns a thenable (an async refinement, or an output that is itself a promise),
+the `async` arrow awaits it, then evaluates the remaining arguments (`await`ing their validations)
+and calls the handler: the order of evaluation, the error of the first invalid argument and the
+values received by the handler are those of an `async` invoke `await`ing every `validate()`. The
+expressions of the table below are `validate(S, ...)` calls in both forms.
+
+| Parameter                               | Generated expression                                                          |
+| --------------------------------------- | ----------------------------------------------------------------------------- |
+| `@Param('id') id: T`                    | `coerce.X(ctx.params['id'], 'param "id"')` (see below)                        |
+| `@Param('id', S)`                       | `validate(S, ctx.params['id'], 'param "id"')`                                 |
+| `@Param()`                              | `ctx.params as never` · with schema: `validate(S, ctx.params, 'params')`      |
+| `@Query('page') page: T`                | `coerce.X(ctx.query['page'], 'query "page"')`                                 |
+| `@Query('page', S)`                     | `validate(S, ctx.query['page'], 'query "page"')`                              |
+| `@Query()` / `@Query(S)`                | `ctx.query as never` / `validate(S, ctx.query, 'query')`                      |
+| `@Body()` / `@Body(S)` / `@Validate(S)` | `ctx.body as never` / `validate(S, ctx.body, 'body')`                         |
+| `@Headers('X-Api-Key') key: T`          | `coerce.X(ctx.headers['x-api-key'], 'header "x-api-key"')` (name lower-cased) |
+| `@Headers()`                            | `ctx.headers as never`                                                        |
+| `@Cookie('sid') sid: T`                 | `coerce.X(ctx.cookies['sid'], 'cookie "sid"')` (or `coerce.optional(...)`)    |
+| `@Cookie('sid', S)`                     | `validate(S, ctx.cookies['sid'], 'cookie "sid"')`                             |
+| `@Cookie()` / `@Cookie(S)`              | `ctx.cookies as never` / `validate(S, ctx.cookies, 'cookies')`                |
+| `@SignedCookie('sid') sid: T`           | `coerce.X(ctx.signedCookie('sid'), 'cookie "sid"')`                           |
+| `@SignedCookie('sid', S)`               | `validate(S, ctx.signedCookie('sid'), 'cookie "sid"')`                        |
+| `@Req()` / `@Res()`                     | `ctx.request as never` / `ctx.response as never` (+ `rawResponse: true`)      |
+| `@UploadedFile('f') f: File`            | `uploads.file(ctx, 'f')` · optional: `uploads.optionalFile(ctx, 'f')`         |
+| `@UploadedFiles('f') f: File[]`         | `uploads.files(ctx, 'f')` · optional: `uploads.optionalFiles(ctx, 'f')`       |
+| `@UploadedFile()` / `@UploadedFiles()`  | the same helpers with `undefined` as field (any field)                        |
+| `@Ctx()`                                | `ctx`                                                                         |
 
 `coerce.X` by declared type (`T`):
 
@@ -2187,6 +2247,8 @@ function validate<S extends StandardSchemaV1>(
   location: string,
 ): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>>
 
+function isThenable(value: unknown): value is PromiseLike<unknown> // a `then` method: validate() result to await
+
 const uploads: {
   file(ctx: HttpContext, field: string | undefined): File // 400 `Missing file "field"` when absent
   optionalFile(ctx: HttpContext, field: string | undefined): File | undefined
@@ -2199,8 +2261,9 @@ Every coercion failure throws `BadRequestException` (400); `validate` throws `Va
 (400, `details: [{ path, message }]`) and `TypeError` when `schema` is not a Standard Schema; the
 `uploads` helpers read `ctx.files` (`undefined` field: every field) and throw `BadRequestException`
 for missing required files (`Expected a file in field "f", received a text value` when the field
-was sent as text). Generated modules import them with
-`import { coerce, uploads, validate } from '@znight/http'` and the context type with
+was sent as text). `validate` returns the output synchronously when the schema validates
+synchronously, a promise otherwise. Generated modules import them with
+`import { coerce, isThenable, uploads, validate } from '@znight/http'` and the context type with
 `import type { HttpContext } from '@znight/http'`.
 
 ### Manifest
@@ -2246,6 +2309,62 @@ Controllers are stored in identity order of the classes; sort them by `token` fo
 output. The effective metadata of a route is the controller's entries whose `group` has no entry on
 the route, then the route's entries.
 
+### Route metadata in other extensions
+
+Extensions whose own targets carry route decorators (WebSocket gateways, GraphQL resolvers) read
+them with the functions of `@znight/http/compiler`, which apply exactly the rules of controllers and
+routes (RFC 0001 groups). They are stable API, like the types above, and the entry stays
+runtime-free (it never loads the HTTP runtime):
+
+| Function                             | What it does                                                                                                                                                                                                                                                                                              |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readRouteMeta(ctx, cls, method?)`   | The `MetaEntry[]` of the route decorators applied to a class (`method` omitted) or to one of its methods, in source order. Works with the `AnalyzeContext` of any extension. Problems (uncalled decorator, two decisions of one group...) are reported as ZNIGHT005, once per call: read each target once |
+| `effectiveRouteMeta(classMeta, own)` | The effective metadata of a method: the class entries whose group the method does not decide, then the method entries (the rule of `ctx.route.meta`)                                                                                                                                                      |
+| `requiredRouteGroups(ctx, applied?)` | The `RequiredRouteGroup[]` of the application (in the `ValidateContext` of any extension): every group declared `required`, applied anywhere or not. `applied` are the entries the caller read. Inconsistent definitions are left out (the http extension reports them)                                   |
+
+A `RequiredRouteGroup` has `group`, `decorators` (`RouteGroupMember[]`, source order: `identity`,
+`name`, `key`, `group`, `required`, `definition`, `flag`) and `suggestion`
+(`@Public(), @Authenticated() or @Roles(...)`). A target of the extension without a decision of a
+required group is **ZNIGHT023**, reported by the extension itself:
+
+```ts
+import type { CompilerExtension, Location } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+
+import { readRouteMeta, requiredRouteGroups } from '@znight/http/compiler'
+
+interface GatewayData {
+  readonly name: string
+  readonly meta: readonly MetaEntry[] // the class entries (methods: effectiveRouteMeta(classMeta, own))
+  readonly location: Location
+}
+
+const ws: CompilerExtension<GatewayData> = {
+  apiVersion: 1,
+  name: 'ws',
+  decorators: { '@acme/ws#Gateway': { targets: ['class'], params: [] } },
+  analyzeClass(cls, ctx) {
+    ctx.store({ name: cls.displayName, meta: readRouteMeta(ctx, cls), location: cls.location })
+  },
+  validate(ctx) {
+    const required = requiredRouteGroups(
+      ctx,
+      ctx.stored.flatMap(gateway => gateway.meta),
+    )
+    for (const gateway of ctx.stored)
+      for (const group of required)
+        if (!gateway.meta.some(entry => entry.group === group.group))
+          ctx.report({
+            code: 'ZNIGHT023',
+            severity: 'error',
+            message: `${gateway.name} has no "${group.group}" decision`,
+            location: gateway.location,
+            hints: [`Add ${group.suggestion} to ${gateway.name}`],
+          })
+  },
+}
+```
+
 ## Writing an adapter
 
 An adapter implements `HttpAdapter` (exported types): it routes requests to the handlers given by

package/dist/compiler.d.mts

@@ -1,5 +1,5 @@
 import { _ as HttpMethod, y as HttpParamSource } from "./adapter-J0UXFnNM.mjs";
-import { ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
+import { AnalyzeContext, ClassInfo, ClassRef, CompilerExtension, Location, MethodInfo, StaticValue, ValidateContext, ValueRef } from "@znight/compiler";
 /** Primitive coercions (`coerce.<kind>`). */
 type ScalarCoercion = "string" | "number" | "integer" | "boolean" | "bigint" | "date";
 /**
@@ -150,7 +150,82 @@ interface HttpControllerData {
   /** Location of the base path argument (the decorator when absent). */
   readonly pathLocation: Location;
 }
+/** A route decorator definition of the application (`export const Roles = createRouteDecorator(...)`). */
+interface RouteGroupMember {
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string;
+  /** Name of the `const` (`Roles`). */
+  readonly name: string;
+  readonly key: string;
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string;
+  readonly required: boolean;
+  /** Location of the definition. */
+  readonly definition: Location;
+  /**
+   * A flag (`@Public()`): created without type argument, and applied without argument wherever it
+   * was seen. Decides how the decorator is suggested: `@Public()` or `@Roles(...)`.
+   */
+  readonly flag: boolean;
+}
+/** A required route decorator group: every route-like target must carry a decision of it. */
+interface RequiredRouteGroup {
+  /** Group name (`access`). */
+  readonly group: string;
+  /** The decorators of the group, in source order (file, then position). Never empty. */
+  readonly decorators: readonly RouteGroupMember[];
+  /** The decorators as a hint: `@Public(), @Authenticated() or @Roles(...)`. */
+  readonly suggestion: string;
+}
+/**
+ * The required route decorator groups of the application (RFC 0001): what every route-like target
+ * of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+ * A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+ *
+ * `applied` are the route metadata entries the caller read on its own targets
+ * ({@link readRouteMeta}): they make decorators known even when the compiler has no
+ * `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+ * not reported here: the http extension reports them (ZNIGHT005) once.
+ *
+ * ```ts
+ * validate(ctx) {
+ *   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+ *   for (const gateway of ctx.stored)
+ *     for (const group of required)
+ *       if (!gateway.meta.some(entry => entry.group === group.group))
+ *         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+ *           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+ * }
+ * ```
+ */
+export declare function requiredRouteGroups(ctx: ValidateContext<unknown>, applied?: Iterable<MetaEntry>): readonly RequiredRouteGroup[];
+/**
+ * The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+ * decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+ * as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+ * `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+ * once. Decorators that are not route decorators are ignored.
+ *
+ * Works with the analysis context of any extension. The entries of a target are its own: combine a
+ * class and a method with {@link effectiveRouteMeta}.
+ *
+ * ```ts
+ * analyzeClass(cls, ctx) {
+ *   const classMeta = readRouteMeta(ctx, cls)
+ *   for (const method of cls.methods) {
+ *     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+ *   }
+ * }
+ * ```
+ */
+export declare function readRouteMeta(ctx: AnalyzeContext<unknown>, cls: ClassInfo, method?: MethodInfo): MetaEntry[];
+/**
+ * The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+ * the class entries, except those of a group the method decides itself, then the method entries.
+ * The same rule as `ctx.route.meta` at runtime.
+ */
+export declare function effectiveRouteMeta(classMeta: readonly MetaEntry[], methodMeta: readonly MetaEntry[]): MetaEntry[];
 /** The `@znight/http` compiler extension. */
 declare const http: CompilerExtension<HttpControllerData>;
-export { type CoercionPlan, type HttpControllerData, type HttpParamData, type HttpRouteData, type MetaEntry, type ParamCoercion, type ScalarCoercion, type SseRouteData, type UploadData, http as default };
+export { type CoercionPlan, type HttpControllerData, type HttpParamData, type HttpRouteData, type MetaEntry, type ParamCoercion, type RequiredRouteGroup, type RouteGroupMember, type ScalarCoercion, type SseRouteData, type UploadData, http as default };
 //# sourceMappingURL=compiler.d.mts.map