@znight/http 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1254 @@
+import { $ as PayloadTooLargeException, A as UploadedFileOptions, B as BadRequestException, C as HttpUploadDefinition, Ct as CookieOptions, D as RequestAbortedError, Dt as parseSetCookie, E as RequestAbortKind, Et as parseCookieHeader, F as formatByteSize, G as HeaderValue, H as ForbiddenException, I as parseByteSize, J as HttpExceptionOptions, K as HttpErrorBody, L as QueryRecord, M as Uploads, N as uploads, O as RequestId, Ot as serializeClearCookie, P as ByteSize, Q as NotImplementedException, R as parseQuery, S as HttpSseDefinition, St as CookieDefaults, T as HttpRouteInfo, Tt as SetCookieInfo, U as GatewayTimeoutException, V as ConflictException, W as GoneException, X as MethodNotAllowedException, Y as InternalServerErrorException, Z as NotFoundException, _ as HttpMethod, _t as StandardSchemaV1Result, a as AdapterRoute, at as ValidationException, b as HttpRouteDefinition, bt as isStandardSchema, c as HttpServerAddress, ct as toIssueDetail, d as InjectStreamOptions, dt as StandardSchemaV1, et as ServiceUnavailableException, f as InjectStreamRequest, ft as StandardSchemaV1FailureResult, g as HttpMetadata, gt as StandardSchemaV1Props, h as HttpControllerDefinition, ht as StandardSchemaV1PathSegment, i as AdapterRequest, it as UnsupportedMediaTypeException, j as UploadedFilesOptions, k as UploadLimits, kt as serializeCookie, l as InjectRequest, lt as InferSchemaInput, m as ReplyBody, mt as StandardSchemaV1Options, n as AdapterHandler, nt as UnauthorizedException, o as FallbackHandler, ot as ValidationIssueDetail, p as InjectStreamResponse, pt as StandardSchemaV1Issue, q as HttpException, r as AdapterReply, rt as UnprocessableEntityException, s as HttpAdapter, st as isHttpException, t as AdapterCloseOptions, tt as TooManyRequestsException, u as InjectResponse, ut as InferSchemaOutput, v as HttpParamDefinition, vt as StandardSchemaV1SuccessResult, w as HttpContext, wt as ResponseCookie, x as HttpRouteGroupDefinition, xt as ClearCookieOptions, y as HttpParamSource, yt as StandardSchemaV1Types, z as BadGatewayException } from "./adapter-CGSceVEN.mjs";
+import { NodeAdapter, NodeAdapterOptions, nodeAdapter } from "./node.mjs";
+import { ClassMarker, Container, MethodMarker, ParameterMarker, Plugin, PluginContext, PluginOptions, ProviderKey, Scope, TypedToken } from "@znight/core";
+/**
+ * Origins allowed to read responses: `'*'` (any origin), an exact origin
+ * (`'https://app.example.com'`), an anchored `RegExp` (`/^https:\/\/[a-z0-9-]+\.example\.com$/`), a
+ * list of those, or a function (awaited; a function that throws or rejects denies the origin).
+ */
+type CorsOrigin = "*" | string | RegExp | readonly (string | RegExp)[] | ((origin: string) => boolean | Promise<boolean>);
+/** The `cors` option of `HttpPlugin.configure`. */
+interface CorsOptions {
+  /** Allowed origins (required). */
+  readonly origin: CorsOrigin;
+  /** `access-control-allow-credentials: true` (cookies, `Authorization`). Not with `'*'`. Default `false`. */
+  readonly credentials?: boolean;
+  /**
+   * `access-control-allow-methods` of preflights. Default: the methods routed on the requested path.
+   * `'*'` (any method) is refused with `credentials`, where browsers read it as a method named `*`.
+   */
+  readonly methods?: readonly string[];
+  /**
+   * `access-control-allow-headers` of preflights. Default: the headers the browser asks for
+   * (`access-control-request-headers`). `'*'` is refused with `credentials`; it covers
+   * `Authorization` too (sent as `*, authorization` when the browser asks for it: browsers never let
+   * `*` alone cover it).
+   */
+  readonly allowHeaders?: readonly string[] | "*";
+  /**
+   * `access-control-expose-headers` of replies. Default: the request id header (none when it is
+   * `false`). `'*'` (every header) is refused with `credentials`, where browsers read it literally.
+   */
+  readonly exposeHeaders?: readonly string[];
+  /** `access-control-max-age` of preflights, in seconds (0 to 86400). Default `600`. */
+  readonly maxAge?: number;
+}
+/** How a file is presented to the client (`Content-Disposition`). */
+type ContentDispositionType = "attachment" | "inline";
+/** Options of `HttpResponse.file()`. */
+interface FileResponseOptions {
+  /**
+   * Name proposed to the client in `Content-Disposition` (any Unicode name; path separators are
+   * removed). Setting it makes the response an `attachment` unless `disposition` says otherwise.
+   */
+  readonly filename?: string;
+  /**
+   * Media type of the response. Default: the type of the `Blob`, else looked up from the extension
+   * of `filename` / of the path (small built-in table, text types with `charset=utf-8`), else
+   * `application/octet-stream`.
+   */
+  readonly contentType?: string;
+  /**
+   * `attachment` (download) or `inline` (displayed by the browser). Default: `attachment` when
+   * `filename` is set, otherwise no `Content-Disposition` header. Without `filename`, the file name
+   * (path basename, `File.name`) is used.
+   */
+  readonly disposition?: ContentDispositionType;
+  /**
+   * Directory the path is resolved in. The resolved file (symbolic links followed) must stay inside
+   * it: `..` segments, absolute paths and links escaping the directory answer 404. Always set it
+   * when the path comes from the request.
+   */
+  readonly root?: string;
+  /**
+   * With `root`: whether files or directories whose name starts with a dot (`.env`, `.git/config`)
+   * may be sent. Default: `'deny'` (404).
+   */
+  readonly dotfiles?: "allow" | "deny";
+}
+/**
+ * The body of `HttpResponse.file()`: a file on disk or a `Blob`, resolved by the pipeline when the
+ * response is sent (stat, conditional request, range).
+ */
+declare class FileBody {
+  /** Path (`string` / `file:` URL) or `Blob` / `File`. */
+  readonly source: string | URL | Blob;
+  readonly options: FileResponseOptions;
+  constructor(source: string | URL | Blob, options?: FileResponseOptions);
+}
+/** An inclusive byte range. */
+interface ByteRange {
+  readonly start: number;
+  readonly end: number;
+}
+/**
+ * Parses a `Range` header for a representation of `size` bytes. Only a single `bytes` range is
+ * honoured: other units, several ranges and malformed values return `undefined` (the whole
+ * representation is sent, as RFC 9110 allows); a valid range starting after the end returns
+ * `'unsatisfiable'` (416).
+ */
+export declare function parseRange(header: string, size: number): ByteRange | "unsatisfiable" | undefined;
+/**
+ * Builds a `Content-Disposition` header value (RFC 6266): `attachment; filename="report.pdf"`, with
+ * an RFC 8187 / 5987 `filename*` parameter for names that are not plain ASCII
+ * (`attachment; filename="r_sum_.pdf"; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf`). Directory parts and
+ * control characters of `filename` are removed.
+ */
+export declare function contentDisposition(filename?: string, type?: ContentDispositionType): string;
+/** One event of an event stream. */
+interface SseEvent<T = unknown> {
+  /** A string is sent as is; anything else goes through `JSON.stringify` (`toJSON` honoured). */
+  readonly data?: T;
+  /** Event type (`addEventListener(type)`). The client defaults to `message`. No CR or LF. */
+  readonly event?: string;
+  /** Last event id, echoed by the client as `Last-Event-ID`. No CR, LF or NUL. `''` resets it. */
+  readonly id?: string | number;
+  /** Reconnection delay in ms (a safe integer ≥ 0). */
+  readonly retry?: number;
+  /** Comment lines, ignored by `EventSource` (debugging, padding). */
+  readonly comment?: string;
+}
+/** Options of `@Sse()` and `HttpResponse.sse()`. */
+interface SseOptions {
+  /**
+   * Milliseconds without an event after which a keep-alive comment (`:`) is sent (an integer
+   * from 1 000 to 2 147 483 647). `false` disables it. Default: the plugin option `sse.heartbeat`
+   * (8 000).
+   */
+  readonly heartbeat?: number | false;
+  /**
+   * Client reconnection delay (`retry:`, ms), sent first. Default: the plugin option `sse.retry`
+   * (none: browsers use about 3 s).
+   */
+  readonly retry?: number;
+  /**
+   * The server ends the stream gracefully after this many ms (load rebalancing, re-authentication):
+   * `ctx.signal` aborts (`'expired'`), then the client gets a jittered `retry` and reconnects. An
+   * integer from 1 000 to 2 147 483 647 (about 24.8 days, the longest timer). Default: none.
+   */
+  readonly maxDuration?: number;
+}
+/**
+ * What `@Sse` handlers and `HttpResponse.sse()` accept: an async iterable (async generators,
+ * `EventChannel`, a Node.js `Readable` of raw bytes), an iterable (arrays, sync generators; not
+ * strings) or a `ReadableStream`, of `SseEvent` objects or `Uint8Array` chunks (already-framed SSE
+ * text, written as is: proxying an upstream event stream).
+ */
+type SseSource = AsyncIterable<SseEvent | Uint8Array> | Iterable<SseEvent> | ReadableStream<SseEvent | Uint8Array>;
+/** The body of `HttpResponse.sse()`: an event source and its options (served by the plugin). */
+declare class SseBody {
+  readonly source: SseSource;
+  readonly options: SseOptions;
+  constructor(source: SseSource, options?: SseOptions);
+}
+/**
+ * Encodes one event (WHATWG framing): one `: <line>` per comment line, `id:`, `event:`, `retry:`,
+ * then one `data: <line>` per line of the data (split on CRLF, CR and LF, so data can never inject
+ * fields or end the event early), and an empty line. An `event` without `data` gets an empty
+ * `data:` line (otherwise `EventSource` would not dispatch it); events with only `id`, `retry` or
+ * `comment` have no data line.
+ *
+ * ```ts
+ * encodeSseEvent({ id: 41, event: 'status', data: { status: 'paid' } })
+ * // 'id: 41\nevent: status\ndata: {"status":"paid"}\n\n'
+ * ```
+ *
+ * @throws TypeError for anything but a plain object with the keys of {@link SseEvent} (strings,
+ *   numbers, `null`: yield `{ data: value }`), an empty event, an `event` / `id` with CR or LF (NUL
+ *   for `id`), a `retry` that is not an integer ≥ 0, a `data` JSON cannot serialise.
+ */
+export declare function encodeSseEvent(event: SseEvent): string;
+/**
+ * A stream source accepted by `HttpResponse.stream()`: a Web `ReadableStream`, a Node.js `Readable`
+ * or any async iterable (async generator...) of `Uint8Array` / `string` chunks (strings are encoded
+ * as UTF-8).
+ */
+type StreamSource = ReadableStream<Uint8Array | string> | AsyncIterable<Uint8Array | string>;
+/** Options of {@link HttpResponse.stream}. */
+interface StreamResponseOptions {
+  /** Media type. Default: from the extension of `filename`, else `application/octet-stream`. */
+  readonly contentType?: string;
+  /** Name proposed to the client (`Content-Disposition: attachment` unless `disposition` says otherwise). */
+  readonly filename?: string;
+  /** `attachment` or `inline`. Default: `attachment` when `filename` is set, otherwise no header. */
+  readonly disposition?: ContentDispositionType;
+}
+/** Options of {@link HttpResponse}. */
+interface HttpResponseInit {
+  /** Status code. Default: the route default (`@HttpCode`, 201 for POST, 204 without body, 200). */
+  readonly status?: number;
+  /** Response headers (names are case-insensitive; arrays send the header several times). */
+  readonly headers?: Readonly<Record<string, HeaderValue>>;
+  /** Cookies to set (see {@link HttpResponse.withCookie}), in order. */
+  readonly cookies?: readonly ResponseCookie[];
+}
+/** Redirect statuses accepted by {@link HttpResponse.redirect}. */
+type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+/**
+ * A handler result carrying a status and headers next to the body. The body is serialised with the
+ * usual rules (objects → JSON, strings → text, bytes and streams → octet-stream).
+ *
+ * ```ts
+ * @Post('/')
+ * async create(@Body(CreateUser) input: CreateUser): Promise<HttpResponse<User>> {
+ *   const user = await this.users.create(input)
+ *   return HttpResponse.created(user, `/users/${user.id}`)
+ * }
+ * ```
+ *
+ * Status precedence: `@HttpCode` > `HttpResponse.status` > route default.
+ */
+export declare class HttpResponse<T = unknown> {
+  #private;
+  readonly body: T;
+  readonly status: number | undefined;
+  readonly headers: Readonly<Record<string, HeaderValue>>;
+  /** Cookies set by this response (`withCookie` / `withoutCookie`), in order; they win over `ctx.setCookie()`. */
+  readonly cookies: readonly ResponseCookie[];
+  constructor(body: T, init?: HttpResponseInit);
+  /** `200 OK` with `body`. */
+  static ok<T>(body: T, headers?: Readonly<Record<string, HeaderValue>>): HttpResponse<T>;
+  /**
+   * `201 Created`, with a `location` header when given. With a body, the response is typed with it
+   * (`Promise<HttpResponse<BookResponse>>` type-checks).
+   */
+  static created(): HttpResponse<undefined>;
+  static created<T>(body: T, location?: string): HttpResponse<T>;
+  /** `202 Accepted`, typed with its body when there is one. */
+  static accepted(): HttpResponse<undefined>;
+  static accepted<T>(body: T): HttpResponse<T>;
+  /** `204 No Content`. */
+  static noContent(): HttpResponse<undefined>;
+  /** A redirect (`302 Found` by default) to `location`. */
+  static redirect(location: string, status?: RedirectStatus): HttpResponse<undefined>;
+  /**
+   * Sends a file from disk (`string` path or `file:` URL) or a `Blob` / `File`, streamed with
+   * `Content-Length`, `Content-Type` (from the extension, see `contentTypeFor`), `Last-Modified`,
+   * `ETag` and `Accept-Ranges`. Conditional requests answer 304 / 412 and single byte ranges 206
+   * (416 when unsatisfiable). A missing file answers 404.
+   *
+   * ```ts
+   * @Get('/reports/:name')
+   * download(@Param('name') name: string) {
+   *   // `root` confines the path: '../../etc/passwd' answers 404
+   *   return HttpResponse.file(name, { root: REPORTS_DIR, filename: `rapport ${name}` })
+   * }
+   * ```
+   *
+   * Never pass a path built from the request without `root`.
+   */
+  static file(file: string | URL | Blob, options?: FileResponseOptions): HttpResponse<FileBody>;
+  /**
+   * Streams a Web `ReadableStream`, a Node.js `Readable` or an async iterable (async generator) of
+   * `Uint8Array` / `string` chunks. The source is read as the client receives the data
+   * (backpressure) and cancelled when the client disconnects; it runs in the request scope.
+   *
+   * ```ts
+   * @Get('/export.csv')
+   * export() {
+   *   return HttpResponse.stream(this.rows.csvLines(), { filename: 'export.csv' }) // text/csv; charset=utf-8
+   * }
+   * ```
+   */
+  static stream(source: StreamSource, options?: StreamResponseOptions): HttpResponse<ReadableStream<Uint8Array>>;
+  /**
+   * An event stream (Server-Sent Events) on any route and any method: `200` unless `@HttpCode` or
+   * {@link withStatus} say otherwise (`EventSource` requires 200; `fetch()` clients read any status),
+   * even on `POST` routes. Same source, framing and lifecycle as an `@Sse()` route.
+   *
+   * ```ts
+   * @Post('/:id/assistant')
+   * assistant(@Param('id') id: string, @Body(Prompt) prompt: Prompt, @Ctx() ctx: HttpContext) {
+   *   return HttpResponse.sse(this.llm.complete(id, prompt, { signal: ctx.signal }))
+   * }
+   * ```
+   */
+  static sse(source: SseSource, options?: SseOptions): HttpResponse<SseBody>;
+  /** A copy of this response with `name` set to `value`. */
+  withHeader(name: string, value: HeaderValue): HttpResponse<T>;
+  /** A copy of this response with another status. */
+  withStatus(status: number): HttpResponse<T>;
+  /**
+   * A copy of this response setting a cookie, with the secure defaults (`Path=/; Secure; HttpOnly;
+   * SameSite=Lax`, see the plugin option `cookies.defaults`). It replaces a cookie with the same name,
+   * domain and path set by `ctx.setCookie()` or an earlier `withCookie()`.
+   *
+   * ```ts
+   * return HttpResponse.ok({ id: user.id }).withCookie('__Host-uid', user.id, { signed: true, maxAge: 8 * 3600 })
+   * ```
+   *
+   * The name, the value, the lifetime, the domain, the path and the size are checked now; the rules
+   * depending on the plugin (`secure` default with a prefix or `SameSite=None`, signing, the final
+   * size) when the response is sent: a violation then answers a generic 500, logged as
+   * `Invalid cookie "name": …`.
+   *
+   * @throws TypeError / RangeError for an invalid cookie.
+   */
+  withCookie(name: string, value: string, options?: CookieOptions): HttpResponse<T>;
+  /** A copy of this response clearing a cookie (see `ctx.clearCookie()`). */
+  withoutCookie(name: string, options?: ClearCookieOptions): HttpResponse<T>;
+}
+/** Whether `value` is an {@link HttpResponse} (also across duplicated package copies). */
+export declare function isHttpResponse(value: unknown): value is HttpResponse;
+/**
+ * A guard decides whether a request may reach the handler. Guards run in order: global (plugin
+ * options) → controller (`@UseGuard` on the class) → route. Returning `false` responds
+ * `403 Forbidden`; throw an `HttpException` (e.g. `UnauthorizedException`) for another response.
+ *
+ * ```ts
+ * @Injectable()
+ * export class RolesGuard implements CanActivate {
+ *   canActivate(ctx: HttpContext): boolean {
+ *     const roles = Roles.get(ctx) // route metadata from createRouteDecorator
+ *     return roles === undefined || roles.some(role => currentUser(ctx).roles.includes(role))
+ *   }
+ * }
+ * ```
+ */
+interface CanActivate {
+  canActivate(ctx: HttpContext): boolean | Promise<boolean>;
+}
+/** Runs the rest of the interceptor chain and the handler; resolves with the handler result. */
+type CallHandler = () => Promise<unknown>;
+/**
+ * Wraps the handler (after the guards). Interceptors run global → controller → route, the first one
+ * being the outermost. `next()` resolves with the handler result (before serialisation): return it,
+ * transform it, or return something else without calling `next()` (cache hit...).
+ *
+ * ```ts
+ * @Injectable()
+ * export class TimingInterceptor implements HttpInterceptor {
+ *   async intercept(ctx: HttpContext, next: CallHandler) {
+ *     const started = performance.now()
+ *     try {
+ *       return await next()
+ *     } finally {
+ *       ctx.setHeader('server-timing', `handler;dur=${performance.now() - started}`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface HttpInterceptor {
+  intercept(ctx: HttpContext, next: CallHandler): unknown;
+}
+/** What an {@link ExceptionMapper} may return: `undefined` lets the next mapper (or the default) handle the error. */
+type ExceptionMapperResult = HttpException | HttpResponse | Response | undefined;
+/**
+ * Converts errors to responses. Mappers (plugin option `exceptionMappers`) are tried in order for
+ * every error of the pipeline, including `404`/`405`; the first one returning something wins. Return
+ * an `HttpException` to reuse the default error body, an `HttpResponse` or a Web `Response` for full
+ * control, `undefined` to pass.
+ *
+ * ```ts
+ * @Injectable()
+ * export class DomainErrorMapper implements ExceptionMapper {
+ *   map(error: unknown) {
+ *     if (error instanceof UserNotFoundError) return new NotFoundException(error.message)
+ *     return undefined
+ *   }
+ * }
+ * ```
+ */
+interface ExceptionMapper {
+  map(error: unknown, ctx: HttpContext): ExceptionMapperResult | Promise<ExceptionMapperResult>;
+}
+/**
+ * Static side of a guard class: the route decorators whose decisions the guard enforces. Read by
+ * `HttpPlugin` at boot: a route whose decision belongs to a required group (or to a group some
+ * guard enforces) must have a guard enforcing that group in its chain (ZNIGHT023 otherwise).
+ *
+ * ```ts
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   static readonly enforces = [Public, Authenticated, Roles]
+ *   canActivate(ctx: HttpContext) { ... }
+ * }
+ * ```
+ *
+ * Typed with {@link RouteDecoratorInfo} (not `RouteDecorator<unknown>`) so that `[Public, Roles]`
+ * stays assignable under `strictFunctionTypes`.
+ */
+interface GuardEnforcement {
+  readonly enforces?: readonly RouteDecoratorInfo[];
+}
+/** A class producing {@link CanActivate} instances (for `@UseGuard` and plugin options). */
+type GuardClass = (abstract new (...args: never[]) => CanActivate) & GuardEnforcement;
+/** A class producing {@link HttpInterceptor} instances. */
+type HttpInterceptorClass = abstract new (...args: never[]) => HttpInterceptor;
+/** A class producing {@link ExceptionMapper} instances. */
+type ExceptionMapperClass = abstract new (...args: never[]) => ExceptionMapper;
+/** Options of {@link Controller} (static). */
+interface ControllerOptions {
+  /** Base path of every route of the controller (`/users`). Default: `/`. */
+  readonly path?: string;
+  /** Provider scope. Default: `singleton`; `request` creates one controller per request. */
+  readonly scope?: Scope;
+}
+/**
+ * Declares a controller: a provider (singleton by default) whose decorated methods are routes.
+ *
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   constructor(private readonly users: UserService) {}
+ *
+ *   @Get('/:id')
+ *   find(@Param('id') id: number) {
+ *     return this.users.findById(id)
+ *   }
+ * }
+ * ```
+ *
+ * @param pathOrOptions static: base path, or `{ path?, scope? }`.
+ */
+export declare function Controller(_pathOrOptions?: string | ControllerOptions): ClassMarker;
+/** `GET` route. `path` (static) is relative to the controller path; default: the controller path. */
+export declare function Get(_path?: string): MethodMarker;
+/** `POST` route (default status 201). */
+export declare function Post(_path?: string): MethodMarker;
+/** `PUT` route. */
+export declare function Put(_path?: string): MethodMarker;
+/** `PATCH` route. */
+export declare function Patch(_path?: string): MethodMarker;
+/** `DELETE` route. */
+export declare function Delete(_path?: string): MethodMarker;
+/** `HEAD` route (`GET` routes already answer `HEAD` requests). */
+export declare function Head(_path?: string): MethodMarker;
+/** `OPTIONS` route (paths without one answer `OPTIONS` with `204` and an `allow` header). */
+export declare function Options(_path?: string): MethodMarker;
+/** Route for GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS (methods without a dedicated route on the same path). */
+export declare function All(_path?: string): MethodMarker;
+/**
+ * A `GET` route serving an event stream (Server-Sent Events). The handler returns an
+ * `AsyncIterable`, an `Iterable` or a `ReadableStream` of `SseEvent` (`{ data, event, id, retry,
+ * comment }`), or an `HttpResponse` / exception for other outcomes (204 stops `EventSource`). The
+ * plugin frames the events, sends heartbeats, stops the source when the client leaves (`ctx.signal`)
+ * and closes the stream gracefully on shutdown.
+ *
+ * ```ts
+ * @Sse('/:id/events', { retry: 5_000 })
+ * async events(@Param('id') id: string, @Ctx() ctx: HttpContext): Promise<AsyncIterable<SseEvent<OrderEvent>>> {
+ *   if ((await this.orders.find(id)) === undefined) throw new NotFoundException() // pre-flight checks first
+ *   return this.hub.subscribe(id, { signal: ctx.signal })
+ * }
+ * ```
+ *
+ * Prefer an `async` method returning the source over an `async *` generator: the body of a
+ * generator only runs once the 200 and the headers are sent.
+ *
+ * @param path static: route path (relative to the controller path).
+ * @param options static: `{ heartbeat?, retry?, maxDuration? }` (see `SseOptions`).
+ */
+export declare function Sse(path?: string, options?: SseOptions): MethodMarker;
+export declare function Sse(options: SseOptions): MethodMarker;
+/**
+ * Injects a route parameter, coerced to the parameter type (`string`, `number`, `boolean`,
+ * `bigint`, `Date`, literal unions) or validated with `schema`. Without arguments: every parameter
+ * (`Record<string, string>`).
+ *
+ * ```ts
+ * @Get('/:id')
+ * find(@Param('id') id: number) {}
+ * ```
+ *
+ * @param name static: name of a `:param` of the route path.
+ * @param schema value: a Standard Schema validating the raw string (its output is injected).
+ */
+export declare function Param(): ParameterMarker;
+export declare function Param(name: string, schema?: StandardSchemaV1): ParameterMarker;
+export declare function Param(schema: StandardSchemaV1): ParameterMarker;
+/**
+ * Injects a query parameter (coerced to the parameter type; `T[]` accepts repeated and single
+ * values; optional when the parameter is optional or has a default) or, without name, the whole
+ * query (`Record<string, string | string[]>`), typically validated with a schema.
+ *
+ * ```ts
+ * list(@Query('page') page = 1, @Query('tag') tags: string[] = []) {}
+ * search(@Query(SearchQuery) query: SearchQuery) {}
+ * ```
+ *
+ * @param name static: query key.
+ * @param schema value: a Standard Schema (its output is injected).
+ */
+export declare function Query(): ParameterMarker;
+export declare function Query(name: string, schema?: StandardSchemaV1): ParameterMarker;
+export declare function Query(schema: StandardSchemaV1): ParameterMarker;
+/**
+ * Injects a request cookie (decoded, coerced to the parameter type like `@Headers`: `string`,
+ * `number`, `boolean`, `bigint`, `Date`, literal unions, enums, branded primitives) or validated
+ * with `schema`; without name, every cookie (`Record<string, string>`). An absent cookie answers 400
+ * `Missing cookie "name"` unless the parameter is optional. Error messages never echo the value.
+ *
+ * ```ts
+ * // a stale or forged value falls back instead of answering 400 until the cookie expires
+ * export const Theme = z.enum(['light', 'dark']).catch('light')
+ *
+ * read(@Cookie('theme', Theme) theme: 'light' | 'dark', @Cookie('visits') visits = 0) {}
+ * ```
+ *
+ * @param name static: cookie name (an RFC 9110 token).
+ * @param schema value: a Standard Schema (its output is injected).
+ */
+export declare function Cookie(): ParameterMarker;
+export declare function Cookie(name: string, schema?: StandardSchemaV1): ParameterMarker;
+export declare function Cookie(schema: StandardSchemaV1): ParameterMarker;
+/**
+ * Injects the **verified** value of a signed cookie (set with `{ signed: true }`, plugin option
+ * `cookies.secrets`): absent, tampered or signed with a retired key, the cookie does not exist
+ * (400 `Missing cookie "name"` unless the parameter is optional). Same coercion and schema rules as
+ * {@link Cookie}. A route reading a signed cookie fails the boot when `cookies.secrets` is not set.
+ *
+ * @param name static: cookie name.
+ * @param schema value: a Standard Schema (its output is injected).
+ */
+export declare function SignedCookie(_name: string, _schema?: StandardSchemaV1): ParameterMarker;
+/**
+ * Injects the parsed request body, validated with `schema` when given (the schema output is
+ * injected: defaults, transforms, stripped keys). A non-primitive body without schema is reported
+ * by the compiler (ZNIGHT017).
+ *
+ * @param schema value: a Standard Schema (Zod, Valibot, ArkType...).
+ */
+export declare function Body(_schema?: StandardSchemaV1): ParameterMarker;
+/**
+ * Injects a request header (case-insensitive `name`, coerced to the parameter type) or, without
+ * name, every header (`Record<string, string | undefined>`).
+ *
+ * @param name static: header name.
+ */
+export declare function Headers(_name?: string): ParameterMarker;
+/**
+ * Injects a file of a `multipart/form-data` body as a standard `File` (`name`, `type`, `size`,
+ * `arrayBuffer()`, `text()`, `stream()`), held in memory. The route parses multipart bodies before
+ * its interceptors, enforcing the options while the body is read: a file above `maxSize` answers
+ * 413, a refused type 415, a second file in the field or a file in an undeclared field 400, a
+ * missing required file 400, a non-multipart body 415. `@Body()` receives the text fields.
+ *
+ * ```ts
+ * @Post('/avatar')
+ * upload(@UploadedFile('avatar', { maxSize: '2mb', mimeTypes: ['image/png', 'image/jpeg'] }) avatar: File) {}
+ *
+ * @Post('/attachment')
+ * attach(@UploadedFile('file') file?: File) {} // optional: undefined when absent
+ * ```
+ *
+ * `File.name` and `File.type` are sent by the client: never trust them (see the README, "Files").
+ *
+ * @param field static: the multipart field; omitted: the single file of the body, whatever its field.
+ * @param options static: `{ required?, maxSize?, mimeTypes? }`.
+ */
+export declare function UploadedFile(field?: string, options?: UploadedFileOptions): ParameterMarker;
+export declare function UploadedFile(options: UploadedFileOptions): ParameterMarker;
+/**
+ * Injects the files of a multipart field (`File[]`, in body order), or of every field without
+ * `field`. Same rules as {@link UploadedFile}; above `maxFiles` files the request answers 413. An
+ * optional parameter (`files?: File[]`, `required: false`) receives an empty array when no file is
+ * sent.
+ *
+ * ```ts
+ * @Post('/documents')
+ * add(@UploadedFiles('documents', { maxFiles: 5, maxSize: '20mb', mimeTypes: ['application/pdf'] }) documents: File[]) {}
+ * ```
+ *
+ * @param field static: the multipart field; omitted: the files of every field.
+ * @param options static: `{ required?, maxSize?, maxFiles?, mimeTypes? }`.
+ */
+export declare function UploadedFiles(field?: string, options?: UploadedFilesOptions): ParameterMarker;
+export declare function UploadedFiles(options: UploadedFilesOptions): ParameterMarker;
+/**
+ * Sets the maximum request body size of a route, or of every route of a controller (the route wins),
+ * over the plugin `bodyLimit` (and over the limit computed for upload routes). `Infinity` disables
+ * the limit, e.g. for a route streaming its body with `ctx.bodyStream()`.
+ *
+ * ```ts
+ * @Put('/files/:name')
+ * @BodyLimit('5gb')
+ * async store(@Param('name') name: string, @Ctx() ctx: HttpContext) {
+ *   await pipeline(Readable.fromWeb(ctx.bodyStream()), createWriteStream(join(DIR, safeName(name))))
+ * }
+ * ```
+ *
+ * @param size static: bytes (`10_485_760`) or a size with a unit (`'10mb'`, `'512kb'`; `kb` = 1024 bytes).
+ */
+export declare function BodyLimit(_size: ByteSize): ClassMarker & MethodMarker;
+/** Injects the native request of the adapter (escape hatch; the compiler warns). */
+export declare function Req(): ParameterMarker;
+/**
+ * Injects the native response of the adapter (escape hatch; the compiler warns). The handler then
+ * writes the response itself, and must have finished when its promise settles.
+ */
+export declare function Res(): ParameterMarker;
+/** Injects the {@link HttpContext} of the request. */
+export declare function Ctx(): ParameterMarker;
+/**
+ * Sets the status of successful responses (wins over `HttpResponse.status` and the defaults).
+ *
+ * @param status static: an integer between 100 and 599.
+ */
+export declare function HttpCode(_status: number): MethodMarker;
+/**
+ * Adds a header to successful responses. Repeat the decorator for several headers.
+ *
+ * @param name static: header name.
+ * @param value static: header value.
+ */
+export declare function Header(_name: string, _value: string): MethodMarker;
+/**
+ * Protects a controller (every route) or a route with guards (providers implementing
+ * {@link CanActivate}). Order: global guards → controller guards → route guards, each list in
+ * declaration order.
+ *
+ * @param guards value: guard classes.
+ */
+export declare function UseGuard(..._guards: [GuardClass, ...GuardClass[]]): ClassMarker & MethodMarker;
+/**
+ * Wraps a controller (every route) or a route with interceptors (providers implementing
+ * {@link HttpInterceptor}). Order: global → controller → route, the first one being the outermost.
+ *
+ * @param interceptors value: interceptor classes.
+ */
+export declare function UseInterceptor(..._interceptors: [HttpInterceptorClass, ...HttpInterceptorClass[]]): ClassMarker & MethodMarker;
+/**
+ * Validates the request body with `schema`: sugar for `@Body(schema)` on the body parameter (using
+ * both is ZNIGHT005).
+ *
+ * @param schema value: a Standard Schema.
+ */
+export declare function Validate(_schema: StandardSchemaV1): MethodMarker;
+/** Arguments of a route decorator: optional when `T` accepts `undefined` or is `true` (flag decorators). */
+type RouteDecoratorArgs<T> = [T] extends [true] ? [value?: T] : undefined extends T ? [value?: T] : [value: T];
+/** Options of {@link createRouteDecorator} (static). */
+interface RouteDecoratorOptions {
+  /**
+   * Decision group. Decorators of a group are alternatives: one per controller or route, and the
+   * route's decision replaces the controller's. Default: the key (the decorator is its own group).
+   * A letter followed by letters, digits, `_`, `.` or `-`.
+   */
+  readonly group?: string;
+  /**
+   * Every route must carry a decision of the group: ZNIGHT023 at build time when a route has none,
+   * and at boot when no guard of its chain enforces it (see {@link GuardClass}). All the decorators
+   * of a group must agree. Default `false`.
+   */
+  readonly required?: boolean;
+}
+/** The data part of a route decorator: what guards list in `static enforces`. */
+interface RouteDecoratorInfo {
+  /** Key of the value in `route.meta`. */
+  readonly key: string;
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string;
+  /** Every route must carry a decision of the group. */
+  readonly required: boolean;
+}
+/**
+ * A route metadata entry given as data rather than as a decorator: the `meta` of plugin routes
+ * (`[Public.meta()]`). Built by {@link RouteDecorator.meta}.
+ */
+interface RouteMetaEntry<T = unknown> {
+  readonly key: string;
+  readonly value: T;
+  /** Decision group. Default: the key. */
+  readonly group?: string;
+  /** Default `false`. */
+  readonly required?: boolean;
+}
+/** A user-defined route metadata decorator created with {@link createRouteDecorator}. */
+interface RouteDecorator<T> extends RouteDecoratorInfo {
+  (...args: RouteDecoratorArgs<T>): ClassMarker & MethodMarker;
+  /**
+   * The value of the current route, if set. Reads the effective metadata: the route's decision of
+   * a group wins over the controller's.
+   */
+  get(ctx: HttpContext): T | undefined;
+  /**
+   * The same metadata as data (`{ key, value, group, required }`), for routes that are not compiled
+   * controllers (plugin routes: `OpenApiPlugin.configure({ meta: [Public.meta()] })`). The value is
+   * `true` when omitted, like `@Public()`.
+   */
+  meta(...args: RouteDecoratorArgs<T>): RouteMetaEntry<T>;
+}
+/**
+ * Creates a metadata decorator for controllers and routes. The compiler stores its argument
+ * (`value`, statically evaluated or an exported reference; `true` when omitted) in
+ * `meta[key]`, read by guards and interceptors through `ctx.route.meta` or `decorator.get(ctx)`.
+ *
+ * ```ts
+ * export const Public = createRouteDecorator('public', { group: 'access', required: true })
+ * export const Authenticated = createRouteDecorator('authenticated', { group: 'access', required: true })
+ * export const Roles = createRouteDecorator<readonly string[]>('roles', { group: 'access', required: true })
+ *
+ * @Controller('/books')
+ * @Roles(['reader']) // the decision of every route of the controller...
+ * export class BookController {
+ *   @Get('/:id/cover')
+ *   @Public() // ...unless the route has its own decision of the group
+ *   cover() {}
+ * }
+ *
+ * // in a guard
+ * if (Public.get(ctx)) return true
+ * const roles = Roles.get(ctx) ?? []
+ * ```
+ *
+ * Decorators of one `group` are alternatives: two of them on the same class or method are
+ * ZNIGHT005, and the route's decision replaces the controller's (without `group`, each decorator is
+ * its own group: the route value wins over the controller value). With `required: true`, a route
+ * without decision fails the build (ZNIGHT023).
+ *
+ * @param key static: unique metadata key.
+ * @param options static: `{ group?, required? }`.
+ */
+export declare function createRouteDecorator<T = true>(key: string, options?: RouteDecoratorOptions): RouteDecorator<T>;
+/** How the boot check reports problems. */
+type EnforcementMode = "error" | "warn";
+/**
+ * `EventChannel`: a bounded bridge from push-based producers (an event bus, an `EventEmitter`, a
+ * database listener) to a pull-based `AsyncIterable` (an SSE source, a GraphQL subscription), with
+ * no dependency.
+ */
+/** Options of {@link EventChannel}. */
+interface EventChannelOptions {
+  /** Buffered items before `overflow` applies. Default: 1 000. */
+  readonly capacity?: number;
+  /**
+   * What happens when an item is pushed into a full buffer:
+   * - `'drop-oldest'` (default): the oldest buffered item is discarded;
+   * - `'drop-newest'`: the item is discarded (`push()` returns false);
+   * - `'close'`: the item is discarded and the channel closes after the buffered items (an SSE
+   *   client then reconnects and resumes with `Last-Event-ID`).
+   */
+  readonly overflow?: "drop-oldest" | "drop-newest" | "close";
+  /** Closes the channel when aborted (pass `ctx.signal`). */
+  readonly signal?: AbortSignal;
+}
+/**
+ * A bounded, single-consumer queue that is an `AsyncIterable`: producers `push()`, the consumer
+ * iterates. A pending `next()` resolves with `{ done: true }` as soon as the channel closes for any
+ * reason, so an SSE handler built on a channel always stops when its client leaves.
+ *
+ * ```ts
+ * const channel = new EventChannel<SseEvent<Order>>({ capacity: 256, overflow: 'close', signal: ctx.signal })
+ * const unsubscribe = bus.on('order', order => channel.push({ event: 'order', data: order }))
+ * channel.onClose(unsubscribe)
+ * return channel // from an @Sse handler
+ * ```
+ */
+export declare class EventChannel<T> implements AsyncIterable<T> {
+  #private;
+  constructor(options?: EventChannelOptions);
+  /** Buffered items. */
+  get size(): number;
+  /** Whether the channel no longer accepts items (closed, failed, overflowed, aborted, returned). */
+  get closed(): boolean;
+  /** Buffers an item (or hands it to a waiting consumer). Returns false when it was dropped or the channel is closed. */
+  push(item: T): boolean;
+  /** Ends the iteration after the buffered items. Idempotent. */
+  close(): void;
+  /** Makes the iteration throw `error` after the buffered items (ignored once closed). */
+  fail(error: unknown): void;
+  /**
+   * Calls `listener` once when the channel closes (close, fail, overflow, signal, consumer
+   * `return()`); immediately when it is already closed.
+   */
+  onClose(listener: () => void): void;
+  /**
+   * The iterator of the single consumer (a second call throws). Its `return()` closes the channel
+   * and resolves at once, even while a `next()` waits.
+   */
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/**
+ * Client side of Server-Sent Events: the WHATWG "interpreting an event stream" algorithm over a
+ * byte stream (`parseSseStream`), used by `injectSse()` and by tests over real sockets. Import-free.
+ */
+/** A dispatched event. */
+interface SseMessage {
+  /** Event type: `message` by default. */
+  readonly event: string;
+  readonly data: string;
+  /** The last event id at dispatch time (what `EventSource` sends back as `Last-Event-ID`). */
+  readonly id: string;
+  /** `JSON.parse(data)`. */
+  json<T = unknown>(): T;
+}
+/** An item of an event stream: an event, a comment (heartbeats are `''`) or a reconnection delay. */
+type SseItem = ({
+  readonly type: "event";
+} & SseMessage) | {
+  readonly type: "comment";
+  readonly text: string;
+} | {
+  readonly type: "retry";
+  readonly retry: number;
+};
+/** Options of {@link parseSseStream}. */
+interface ParseSseOptions {
+  /** Stops reading (the body is cancelled) when aborted. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Turns an event stream body (a `fetch()` response body, `injectStream().body`) into its items.
+ * UTF-8 is decoded with the BOM stripped; an unterminated event at the end is discarded. Calling
+ * `return()` (leaving a `for await` loop) or aborting `signal` cancels the body.
+ *
+ * ```ts
+ * const response = await fetch(`${http.address}/orders/o-1/events`)
+ * for await (const item of parseSseStream(response.body!)) {
+ *   if (item.type === 'event') console.log(item.event, item.json())
+ * }
+ * ```
+ */
+export declare function parseSseStream(body: ReadableStream<Uint8Array>, options?: ParseSseOptions): AsyncIterableIterator<SseItem>;
+/** Options of {@link InjectSseResponse.next} and {@link InjectSseResponse.take}. */
+interface InjectSseWaitOptions {
+  /** Maximum wait for each event (ms). Default: 2 000. */
+  readonly timeoutMs?: number;
+}
+/** The response of `injectSse()`: an event stream read in memory, like `EventSource` would. */
+interface InjectSseResponse extends AsyncIterable<SseMessage>, AsyncDisposable {
+  readonly status: number;
+  readonly headers: Record<string, string | string[]>;
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+  /** `''` for an event stream; otherwise the whole body, read to its end (an error, a 204...). */
+  readonly body: string;
+  /** `JSON.parse(body)`. */
+  json<T = unknown>(): T;
+  /** The next event (comments skipped). Rejects on timeout (default 2 000 ms) or when the stream ended. */
+  next(options?: InjectSseWaitOptions): Promise<SseMessage>;
+  /** The next `count` events (the timeout applies to each). */
+  take(count: number, options?: InjectSseWaitOptions): Promise<SseMessage[]>;
+  /** Comments received so far (heartbeats are `''`). */
+  readonly comments: readonly string[];
+  /** What a browser would send as `Last-Event-ID` on reconnection. */
+  readonly lastEventId: string;
+  /** The last `retry` received (ms). */
+  readonly retry: number | undefined;
+  /** Resolves when the server ends the stream (reading the remaining events, which stay available to `next()`). */
+  readonly done: Promise<void>;
+  /** Disconnects (cancels the body): the server sees a client disconnect. Idempotent. */
+  close(): Promise<void>;
+  /** Reconnects like `EventSource`: closes this stream and sends the same request plus `last-event-id`. */
+  reconnect(): Promise<InjectSseResponse>;
+}
+/**
+ * The `trustProxy` option: `false` (default: the headers are ignored), a number of trusted hops
+ * (`1`: one load balancer in front of the server), or the addresses of the trusted proxies (IPv4 /
+ * IPv6 addresses, CIDR ranges and the aliases `'loopback'`, `'private'`, `'linklocal'`).
+ */
+type TrustProxy = false | number | readonly string[];
+/** HSTS settings (`strict-transport-security`). */
+interface HstsOptions {
+  /** `max-age`, in seconds. Default `31536000` (one year). */
+  readonly maxAge?: number;
+  /** `includeSubDomains`. Default `true`. */
+  readonly includeSubDomains?: boolean;
+  /** `preload` (needs `includeSubDomains` and a `maxAge` of at least one year). Default `false`. */
+  readonly preload?: boolean;
+}
+/** The `securityHeaders` option of `HttpPlugin.configure` (merged over the defaults). */
+interface SecurityHeadersOptions {
+  /** `content-security-policy`. Default `"default-src 'none'; frame-ancestors 'none'"`. */
+  readonly contentSecurityPolicy?: string | false;
+  /** `x-frame-options`. Default `'DENY'`. */
+  readonly frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  /** `x-content-type-options: nosniff`. Default `true`. */
+  readonly noSniff?: boolean;
+  /** `referrer-policy` (a policy or a comma-separated fallback list). Default `'no-referrer'`. */
+  readonly referrerPolicy?: string | false;
+  /** `strict-transport-security`. Default `false`; `true`: `max-age=31536000; includeSubDomains`. */
+  readonly hsts?: boolean | HstsOptions;
+  /** `cross-origin-resource-policy`. Default `false`. */
+  readonly crossOriginResourcePolicy?: "same-origin" | "same-site" | "cross-origin" | false;
+  /** `cache-control` of replies that do not set one (`'no-store'` for personal data). Default `false`. */
+  readonly cacheControl?: string | false;
+}
+/** How requests whose path ends with an extra `/` are handled. */
+type TrailingSlashPolicy = "strict" | "ignore" | "redirect";
+/** A global guard: a provider class (resolved with the container) or an instance. */
+type GuardRef = GuardClass | CanActivate;
+/** A global interceptor: a provider class or an instance. */
+type InterceptorRef = HttpInterceptorClass | HttpInterceptor;
+/** An exception mapper: a provider class or an instance. */
+type ExceptionMapperRef = ExceptionMapperClass | ExceptionMapper;
+/** Options of {@link HttpPlugin.configure}. */
+interface HttpPluginOptions {
+  /** Server implementation. Default: `nodeAdapter()` (built-in, `node:http`). */
+  readonly adapter?: HttpAdapter;
+  /** Port to listen on (`0` picks a free port). Default: `3000`. */
+  readonly port?: number;
+  /** Interface to bind. Default: `0.0.0.0`. */
+  readonly host?: string;
+  /** Path prefix of every route (`/api`). Default: none. */
+  readonly prefix?: string;
+  /** Guards run before the controller and route guards of every route. */
+  readonly guards?: readonly GuardRef[];
+  /** Interceptors wrapping every route (outermost first). */
+  readonly interceptors?: readonly InterceptorRef[];
+  /** Error-to-response mappers, tried in order (see `ExceptionMapper`). */
+  readonly exceptionMappers?: readonly ExceptionMapperRef[];
+  /**
+   * `strict` (default): `/users/` does not match `/users`. `ignore`: it does. `redirect`: it is
+   * redirected (308) to `/users`.
+   */
+  readonly trailingSlash?: TrailingSlashPolicy;
+  /** Send the message of unexpected errors in 500 responses (development only). Default: `false`. */
+  readonly exposeErrors?: boolean;
+  /**
+   * Maximum request body size (413 above): bytes or a size with a unit (`'10mb'`; `kb` = 1024
+   * bytes), `Infinity` for no limit. Routes override it with `@BodyLimit`; upload routes default to
+   * the sum of their file limits plus this value. Default: 1 MiB.
+   */
+  readonly bodyLimit?: ByteSize;
+  /** Limits of multipart bodies and defaults of the upload parameters (see `UploadLimits`). */
+  readonly uploads?: UploadLimits;
+  /**
+   * Header carrying the request id: reused when the client sends a valid one (≤ 128 characters of
+   * `[A-Za-z0-9_-.:@/+=]`), echoed on every response. `false`: always generate, never echo.
+   * Default: `x-request-id`.
+   */
+  readonly requestIdHeader?: string | false;
+  /** Request id generator. Default: `crypto.randomUUID()`. */
+  readonly generateRequestId?: () => string;
+  /**
+   * Maximum time `onStop` waits for in-flight requests before closing the remaining connections.
+   * Keep it below the application `shutdown.hookTimeoutMs`. `Infinity`: no limit of its own (the
+   * application's `hookTimeoutMs` still bounds `onStop`). Default: 4 000 ms.
+   */
+  readonly drainTimeoutMs?: number;
+  /**
+   * CORS: preflights are answered before routing and guards (never by a route), and replies to
+   * allowed origins get `access-control-allow-origin`, identically on every adapter. Default: off.
+   *
+   * ```ts
+   * cors: { origin: ['https://app.example.com', /^https:\/\/[a-z0-9-]+\.preview\.example\.com$/], credentials: true }
+   * ```
+   */
+  readonly cors?: CorsOptions | false;
+  /**
+   * Security headers added to every reply that does not set them (`@Res()` raw replies excepted):
+   * `true` (default) for the API defaults, an object merged over them, `false` for none.
+   */
+  readonly securityHeaders?: boolean | SecurityHeadersOptions;
+  /**
+   * Proxies trusted for `x-forwarded-for` / `x-forwarded-proto` (`ctx.ip`, `ctx.protocol`): a number
+   * of hops, or addresses, CIDR ranges and the aliases `'loopback'`, `'private'`, `'linklocal'`.
+   * Default `false`: the headers are ignored and `ctx.ip` is the adapter's address.
+   */
+  readonly trustProxy?: TrustProxy;
+  /**
+   * What the boot check of route decisions does when a route misses a decision of a required group,
+   * or when no guard of its chain enforces its decision (ZNIGHT023): `'error'` (default) fails the
+   * boot, `'warn'` logs one warning per group (tests that deliberately run without guards).
+   */
+  readonly enforcement?: EnforcementMode;
+  /** Cookies: signing keys and defaults (see {@link HttpCookieOptions}). */
+  readonly cookies?: HttpCookieOptions;
+  /** Server-Sent Events defaults (see {@link HttpSseOptions}). */
+  readonly sse?: HttpSseOptions;
+}
+/** The plugin option `cookies`. */
+interface HttpCookieOptions {
+  /**
+   * HMAC keys of signed cookies (`@SignedCookie`, `{ signed: true }`), at least 32 bytes each: the
+   * first signs, all verify (rotation: deploy `[next, current]`, wait for the longest cookie
+   * lifetime, then `[next]`). Default: none (signed cookies unavailable).
+   */
+  readonly secrets?: string | Uint8Array | readonly (string | Uint8Array)[];
+  /**
+   * Defaults of every cookie set by the application, merged over the secure defaults
+   * `{ path: '/', secure: true, httpOnly: true, sameSite: 'lax' }` (e.g. `{ secure: false }` for
+   * plain `http://` development setups on a non-localhost host).
+   */
+  readonly defaults?: CookieDefaults;
+}
+/** The plugin option `sse`. */
+interface HttpSseOptions {
+  /** Default heartbeat (ms, an integer ≥ 1 000, or `false`). Default: 8 000. */
+  readonly heartbeat?: number | false;
+  /** Default `retry` sent first (ms). Default: none. */
+  readonly retry?: number;
+  /**
+   * Time an event source gets to finish after `ctx.signal` aborted on shutdown or `maxDuration` (ms),
+   * before the stream ends with a jittered `retry`. Must be lower than `drainTimeoutMs`. Default:
+   * 1 000.
+   */
+  readonly shutdownGraceMs?: number;
+}
+/** A route registered by the plugin (see {@link HttpPlugin.routes}). */
+interface HttpRouteSummary {
+  readonly method: string;
+  /** Registered path, prefix included. */
+  readonly path: string;
+  /** Controller display name, or the name of the plugin declaring the route. */
+  readonly controller: string;
+  readonly handler: string;
+  /** `'controller'` for compiled routes, the plugin name for plugin routes. */
+  readonly source: string;
+  /** Effective route metadata (the nearest decision of each group). */
+  readonly meta: Readonly<Record<string, unknown>>;
+  /** Display names of the guards, in chain order (global, controller, route). */
+  readonly guards: readonly string[];
+}
+/**
+ * The HTTP plugin: serves the controllers compiled into `metadata.extensions.http` with the chosen
+ * adapter.
+ *
+ * ```ts
+ * const app = await Application.create({
+ *   metadata: __ZNIGHT_METADATA__,
+ *   plugins: [HttpPlugin.configure({ port: 3000, prefix: '/api' })],
+ * })
+ * await app.start()
+ * ```
+ *
+ * Lifecycle: `register` declares the request-scoped externals `HttpContext` and `RequestId`;
+ * `onBootstrap` resolves the options, controllers, guards and interceptors, collects the routes of
+ * other plugins (`httpRoutes()`), checks route decisions and registers the routes; `onStart`
+ * listens; `onStop` stops accepting connections and drains in-flight requests (`drainTimeoutMs`);
+ * `onDispose` closes the server.
+ */
+export declare class HttpPlugin implements Plugin {
+  #private;
+  readonly name = "http";
+  private constructor();
+  /**
+   * Creates the plugin. `options` may be a function of the container, evaluated in `onBootstrap`:
+   * `HttpPlugin.configure(c => ({ port: c.get(AppConfig).port }))`.
+   */
+  static configure(options?: PluginOptions<HttpPluginOptions>): HttpPlugin;
+  /** The adapter (available after `onBootstrap`). */
+  get adapter(): HttpAdapter;
+  /** Address of the server once listening (`String(address)` is its URL), `undefined` otherwise. */
+  get address(): HttpServerAddress | undefined;
+  /**
+   * The path prefix of every route (`''` without prefix, `/api`), for plugins that serve routes or
+   * publish URLs. Readable once the plugin is registered (before or after its `onBootstrap`; at any
+   * time when the options are not a function of the container). Throws the options error when
+   * the options are invalid.
+   */
+  get prefix(): string;
+  /** Registered routes (after `onBootstrap`), in registration order. */
+  get routes(): readonly HttpRouteSummary[];
+  /** Number of requests being processed. */
+  get inflight(): number;
+  /** Number of open event streams (`@Sse`, `HttpResponse.sse()`): health checks, gauges, stream caps. */
+  get streams(): number;
+  /**
+   * The signed wire value of a cookie (`<encoded value>.<signature>`, signed with the first secret of
+   * `cookies.secrets`): what a browser would send back after `setCookie(name, value, { signed: true })`.
+   * For gateways minting cookies and for tests. Available after `onBootstrap`.
+   *
+   * @throws TypeError for an invalid name or value; Error without `cookies.secrets`.
+   */
+  signCookie(name: string, value: string): string;
+  /**
+   * The provider classes the plugin resolves in `onBootstrap` although no compiled metadata
+   * references them: the classes of the `guards`, `interceptors` and `exceptionMappers` options
+   * (instances are left out), in that order, without duplicates. `TestApp` from `@znight/testing`
+   * creates them at boot with their dependencies (an async dependency cannot be created on demand);
+   * pass them to `init: { only }` when restricting the boot with `Application.create()`.
+   *
+   * Options given as a function of the container cannot be read before the bootstrap: the result is
+   * then empty. Never throws: invalid options are reported by `onBootstrap`.
+   */
+  initRoots(): readonly ProviderKey[];
+  /**
+   * Sends a request in memory through the adapter and the whole pipeline (no socket; the server
+   * does not need to listen). Available after `onBootstrap`.
+   *
+   * ```ts
+   * const res = await http.inject({ method: 'POST', url: '/users', body: { name: 'Ada' } })
+   * expect(res.status).toBe(201)
+   * expect(res.json()).toEqual({ id: 1, name: 'Ada' })
+   * ```
+   */
+  inject(request: InjectRequest): Promise<InjectResponse>;
+  /**
+   * Sends a request in memory and resolves at the response headers, the body being read as it is
+   * produced (`body`). Cancelling `body` (or aborting `signal`) disconnects the client. Requires an
+   * adapter implementing `injectStream()` (the four built-in ones do).
+   */
+  injectStream(request: InjectStreamOptions): Promise<InjectStreamResponse>;
+  /**
+   * Opens an event stream in memory (`accept: text/event-stream`) and reads its events like
+   * `EventSource`: `next()`, `take()`, `comments`, `retry`, `lastEventId`, `reconnect()`, `close()`
+   * (the server sees a client disconnect). A response that is not an event stream (404, 204...) is
+   * read to its end (`body`). Resolves at the first chunk of the stream (an `@Sse` stream sends
+   * `retry` or a comment at once), or after 2 000 ms for a stream that sends nothing yet; rejects,
+   * naming the request (which is aborted), when no response headers arrive within 2 000 ms.
+   *
+   * ```ts
+   * await using stream = await http.injectSse({ url: '/orders/o-1/events' })
+   * const event = await stream.next() // rejects after 2 000 ms
+   * expect(event.json()).toMatchObject({ status: 'paid' })
+   * ```
+   */
+  injectSse(request: InjectStreamOptions): Promise<InjectSseResponse>;
+  register(ctx: PluginContext): void;
+  onBootstrap(ctx: PluginContext): void;
+  onStart(ctx: PluginContext): Promise<void>;
+  onStop(ctx: PluginContext): Promise<void>;
+  onDispose(): Promise<void>;
+}
+/**
+ * A route served by `HttpPlugin` on behalf of another plugin. It runs through the same pipeline as
+ * controller routes: `http:request` hook, request scope, global guards, then its own `guards`, the
+ * handler, the exception mappers; global interceptors do not wrap it. The handler result is
+ * serialised like a controller result (`HttpResponse`, objects as JSON, strings, streams...).
+ */
+interface PluginRoute {
+  /** `GET` routes also answer `HEAD`; `ALL` registers every method without its own route. */
+  readonly method: HttpMethod;
+  /** Path relative to the `HttpPlugin` prefix, with the controller grammar (`/openapi.json`, `/docs/_assets/*`). */
+  readonly path: string;
+  /** Handler name, shown in `HttpPlugin.routes`, logs and errors (`document`). */
+  readonly name: string;
+  readonly handler: (ctx: HttpContext) => unknown;
+  /**
+   * Route metadata (`[Public.meta()]`): read by guards (`Public.get(ctx)`) and by the boot check of
+   * required route decorator groups. One entry per group.
+   */
+  readonly meta?: readonly RouteMetaEntry[];
+  /** Guards of the route (provider classes or instances), run after the global guards. */
+  readonly guards?: readonly GuardRef[];
+}
+/** What {@link PluginHttpRoutes.httpRoutes} receives. */
+interface PluginHttpRoutesContext {
+  /** The `HttpPlugin` prefix (`''` or `/api`), already applied to the paths of the routes. */
+  readonly prefix: string;
+  /** The application container (initialised). */
+  readonly container: Container;
+}
+/**
+ * Implemented by a plugin that serves HTTP routes. `HttpPlugin` calls `httpRoutes()` once in its
+ * `onBootstrap`, after `container.init()` and whatever the plugin order, then registers the routes
+ * on its adapter. A path that breaks the grammar, or that collides with another route, is ZNIGHT007
+ * naming the plugin.
+ *
+ * ```ts
+ * export class StatusPlugin implements Plugin, PluginHttpRoutes {
+ *   readonly name = 'status'
+ *   httpRoutes(): readonly PluginRoute[] {
+ *     return [{ method: 'GET', path: '/status', name: 'status', handler: () => ({ up: true }), meta: [Public.meta()] }]
+ *   }
+ * }
+ * ```
+ */
+interface PluginHttpRoutes {
+  httpRoutes(context: PluginHttpRoutesContext): readonly PluginRoute[];
+}
+/** A parsed `content-type` header. */
+interface MediaType {
+  /** Lower-case `type/subtype` without parameters. */
+  readonly type: string;
+  /** Lower-case `charset` parameter, when present. */
+  readonly charset: string | undefined;
+}
+/** Parses a `content-type` header value (`application/json; charset=utf-8`). */
+export declare function parseMediaType(header: string | undefined): MediaType | undefined;
+/** Whether `type` is a JSON media type (`application/json`, `application/problem+json`...). */
+export declare function isJsonType(type: string): boolean;
+/**
+ * Parses a buffered request body according to its `content-type` (low-level helper; the request
+ * context parses bodies itself, multipart bodies as they arrive):
+ *
+ * | Content type                          | Result                               |
+ * | ------------------------------------- | ------------------------------------ |
+ * | empty body                            | `undefined`                          |
+ * | `application/json`, `*\/*+json`        | parsed JSON (400 when malformed)     |
+ * | `text/*`                              | string (charset honoured)            |
+ * | `application/x-www-form-urlencoded`   | record (repeated keys → arrays)      |
+ * | `multipart/form-data`                 | `FormData` (every field and file)    |
+ * | anything else, or no content type     | `Uint8Array`                         |
+ *
+ * A `content-encoding` other than `identity` is rejected with 415 (decompression is not supported).
+ */
+export declare function parseBody(bytes: Uint8Array, contentType: string | undefined, contentEncoding?: string | undefined): Promise<unknown>;
+/**
+ * Converts a raw request value (route parameter, query value, header) to `T`, or throws a
+ * `400 Bad Request` naming `label` (`param "id"`, `query "page"`, `header "x-limit"`).
+ * Called by the compiler-generated `invoke` functions.
+ */
+type Coercer<T> = (value: unknown, label: string) => T;
+/** The coercion helpers called by generated code (see the "Compiler contract" of the README). */
+interface Coercers {
+  /** A string. Rejects missing values and repeated query values. */
+  readonly string: Coercer<string>;
+  /** A finite decimal number (`12`, `-1.5`, `1e3`). Rejects `''`, hex, `NaN`, `Infinity`. */
+  readonly number: Coercer<number>;
+  /** A safe integer (`42`, `-7`). */
+  readonly integer: Coercer<number>;
+  /** `true`/`1` → `true`, `false`/`0` → `false` (case-insensitive). */
+  readonly boolean: Coercer<boolean>;
+  /** A bigint (`123`, `-9007199254740993`). */
+  readonly bigint: Coercer<bigint>;
+  /**
+   * A `Date` from an ISO 8601 date (`2024-01-02`, UTC midnight), an ISO 8601 date-time with an
+   * offset (`2024-01-02T03:04:05Z`, `2024-01-02T03:04+02:00`) or a millisecond timestamp.
+   */
+  readonly date: Coercer<Date>;
+  /** One of `values` (string or number literals, compared after coercion). */
+  enum<const T extends readonly (string | number | boolean)[]>(value: unknown, label: string, values: T): T[number];
+  /** An array: a single value becomes a one-element array, each item is coerced with `item`. */
+  array<T>(value: unknown, label: string, item: Coercer<T>): T[];
+  /** `undefined` when the value is missing, otherwise `item(value, label)`. */
+  optional<T>(value: unknown, label: string, item: Coercer<T>): T | undefined;
+}
+/**
+ * Coercion helpers used by generated `invoke` functions for typed parameters without schema:
+ *
+ * ```ts
+ * invoke: (c, ctx) => c.list(
+ *   coerce.number(ctx.params['id'], 'param "id"'),
+ *   coerce.optional(ctx.query['page'], 'query "page"', coerce.integer),
+ *   coerce.array(ctx.query['tag'], 'query "tag"', coerce.string),
+ * )
+ * ```
+ *
+ * Every failure is a `BadRequestException` (400) whose message names the input.
+ */
+export declare const coerce: Coercers;
+/**
+ * Media type of a file name from its extension (`report.pdf` → `application/pdf`, text types with
+ * `; charset=utf-8`), `undefined` when the extension is unknown.
+ */
+export declare function contentTypeFor(filename: string): string | undefined;
+/** Whether the media type `type` (parameters ignored) matches one of `patterns` (`image/png`, `image/*`, `*\/*`). */
+export declare function matchesMediaType(type: string, patterns: readonly string[]): boolean;
+/** Reason phrase of `status` (`404` → `Not Found`), or a generic one for unknown codes. */
+export declare function statusText(status: number): string;
+/** Whether `status` is an integer in the 100–599 range. */
+export declare function isValidStatus(status: unknown): status is number;
+/**
+ * Tokens of the values `@znight/http` supplies to the container. `HttpContext` and `RequestId` are
+ * request-scoped externals (declared in the package manifest): inject them in request-scoped
+ * providers or through `Lazy<HttpContext>`.
+ */
+export declare const HttpTokens: {
+  /** The {@link HttpContext} of the current request (request scope). */
+  readonly Context: TypedToken<HttpContext>;
+  /** The id of the current request (request scope). */
+  readonly RequestId: TypedToken<RequestId>;
+  /** The {@link HttpPlugin} instance (singleton). */
+  readonly Plugin: TypedToken<HttpPlugin>;
+};
+/**
+ * Validates `value` with a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType...)
+ * and returns the schema **output** (defaults applied, transforms run, unknown keys stripped when
+ * the schema strips them).
+ *
+ * Returns synchronously when the schema validates synchronously, a promise otherwise (async
+ * refinements): generated code always `await`s it.
+ *
+ * @param location what is validated, used in the error message: `body`, `query`, `query "page"`,
+ *   `param "id"`, `headers`, `cookie "sid"`, `cookies`...
+ * @throws ValidationException (400, `details: [{ path, message }]`) when the value is invalid. For
+ *   cookies (`cookie "name"`, `cookies`) the issue messages are replaced with `Invalid value`: some
+ *   libraries quote the received value in them (Valibot, ArkType), and cookies often carry tokens.
+ * @throws TypeError when `schema` is not a Standard Schema v1 (a programming error → 500).
+ */
+export declare function validate<S extends StandardSchemaV1>(schema: S, value: unknown, location: string): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>>;
+export { type AdapterCloseOptions, type AdapterHandler, type AdapterReply, type AdapterRequest, type AdapterRoute, BadGatewayException, BadRequestException, type ByteRange, type ByteSize, type CallHandler, type CanActivate, type ClearCookieOptions, type Coercer, type Coercers, ConflictException, type ContentDispositionType, type ControllerOptions, type CookieDefaults, type CookieOptions, type CorsOptions, type CorsOrigin, type EnforcementMode, type EventChannelOptions, type ExceptionMapper, type ExceptionMapperClass, type ExceptionMapperRef, type ExceptionMapperResult, type FallbackHandler, type FileBody, type FileResponseOptions, ForbiddenException, GatewayTimeoutException, GoneException, type GuardClass, type GuardEnforcement, type GuardRef, type HeaderValue, type HstsOptions, type HttpAdapter, type HttpContext, type HttpControllerDefinition, type HttpCookieOptions, type HttpErrorBody, HttpException, type HttpExceptionOptions, type HttpInterceptor, type HttpInterceptorClass, type HttpMetadata, type HttpMethod, type HttpParamDefinition, type HttpParamSource, type HttpPluginOptions, type HttpResponseInit, type HttpRouteDefinition, type HttpRouteGroupDefinition, type HttpRouteInfo, type HttpRouteSummary, type HttpServerAddress, type HttpSseDefinition, type HttpSseOptions, type HttpUploadDefinition, type InferSchemaInput, type InferSchemaOutput, type InjectRequest, type InjectResponse, type InjectSseResponse, type InjectSseWaitOptions, type InjectStreamOptions, type InjectStreamRequest, type InjectStreamResponse, type InterceptorRef, InternalServerErrorException, type MediaType, MethodNotAllowedException, type NodeAdapter, type NodeAdapterOptions, NotFoundException, NotImplementedException, type ParseSseOptions, PayloadTooLargeException, type PluginHttpRoutes, type PluginHttpRoutesContext, type PluginRoute, type QueryRecord, type RedirectStatus, type ReplyBody, type RequestAbortKind, RequestAbortedError, type RequestId, type ResponseCookie, type RouteDecorator, type RouteDecoratorArgs, type RouteDecoratorInfo, type RouteDecoratorOptions, type RouteMetaEntry, type SecurityHeadersOptions, ServiceUnavailableException, type SetCookieInfo, type SseBody, type SseEvent, type SseItem, type SseMessage, type SseOptions, type SseSource, type StandardSchemaV1, type StandardSchemaV1FailureResult, type StandardSchemaV1Issue, type StandardSchemaV1Options, type StandardSchemaV1PathSegment, type StandardSchemaV1Props, type StandardSchemaV1Result, type StandardSchemaV1SuccessResult, type StandardSchemaV1Types, type StreamResponseOptions, type StreamSource, TooManyRequestsException, type TrailingSlashPolicy, type TrustProxy, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, type UploadLimits, type UploadedFileOptions, type UploadedFilesOptions, type Uploads, ValidationException, type ValidationIssueDetail, formatByteSize, isHttpException, isStandardSchema, nodeAdapter, parseByteSize, parseCookieHeader, parseQuery, parseSetCookie, serializeClearCookie, serializeCookie, toIssueDetail, uploads };
+//# sourceMappingURL=index.d.mts.map