@znight/http 0.5.0 → 0.6.0

package/dist/adapter-6qC95ViO.d.mts

@@ -0,0 +1,2163 @@
+import { t as RoutePath } from "./path-JI87C4k8.mjs";
+import { ClassMarker, Container, MethodMarker, ParameterMarker, Plugin, PluginContext, PluginOptions, ProviderKey, Scope, Token } from "@znight/core";
+/**
+ * Cookies (RFC 0006): parsing of the `cookie` request header, canonical value encoding, strict
+ * `Set-Cookie` serialisation (RFC 6265bis: attribute validation, name prefixes, size limits),
+ * `Set-Cookie` parsing (tests) and the response cookie jar.
+ *
+ * This module is import-free (pure functions): safe to import from anywhere, the compiler excepted
+ * (it has its own token grammar).
+ */
+/** Options of a cookie set on a response (`ctx.setCookie()`, `HttpResponse.withCookie()`). */
+interface CookieOptions {
+  /** Lifetime in seconds (integer). `0` or less expires the cookie now. Default: session cookie. */
+  readonly maxAge?: number;
+  /**
+   * Absolute expiry (sent as an IMF-fixdate), in the years 1601 to 9999 (browsers ignore other
+   * years). Browsers cap lifetimes at 400 days: prefer `maxAge` for long-lived cookies.
+   */
+  readonly expires?: Date;
+  /**
+   * Domain (sub-domains included). Default: none, a host-only cookie. `null`: host-only even when
+   * `cookies.defaults` sets a domain. `__Host-` cookies never take the default domain.
+   */
+  readonly domain?: string | null;
+  /** Default: `'/'`. */
+  readonly path?: string;
+  /** Default: `true` (browsers only send it over HTTPS, `http://localhost` excepted). */
+  readonly secure?: boolean;
+  /** Default: `true` (not readable from JavaScript). */
+  readonly httpOnly?: boolean;
+  /** Default: `'lax'`. `'none'` requires `secure`. */
+  readonly sameSite?: "strict" | "lax" | "none";
+  /** CHIPS partitioned cookie. Requires `secure`. Default: `false`. */
+  readonly partitioned?: boolean;
+  /** Chromium `Priority`. Default: none. */
+  readonly priority?: "low" | "medium" | "high";
+  /** Signs the value with the first secret of the plugin option `cookies.secrets`. Default: `false`. */
+  readonly signed?: boolean;
+}
+/** Plugin-wide defaults (`cookies.defaults`). Lifetime and signing are per cookie. */
+type CookieDefaults = Omit<CookieOptions, "maxAge" | "expires" | "signed">;
+/** What identifies a cookie to clear (and keeps prefixed names valid). */
+type ClearCookieOptions = Pick<CookieOptions, "domain" | "path" | "secure" | "httpOnly" | "sameSite" | "partitioned">;
+/** A cookie to send, as given (defaults and signing are applied when the response is serialised). */
+interface ResponseCookie {
+  readonly name: string;
+  /** `undefined`: a clearing cookie. */
+  readonly value: string | undefined;
+  readonly options: CookieOptions;
+}
+/** A parsed `Set-Cookie` line (see {@link parseSetCookie}). */
+interface SetCookieInfo {
+  readonly name: string;
+  /** Decoded value (a signed cookie: `"<value>.<signature>"`, decoded). */
+  readonly value: string;
+  /** The header line. */
+  readonly raw: string;
+  readonly expires?: Date;
+  readonly maxAge?: number;
+  readonly domain?: string;
+  readonly path?: string;
+  readonly secure: boolean;
+  readonly httpOnly: boolean;
+  readonly sameSite?: "strict" | "lax" | "none";
+  readonly partitioned: boolean;
+  readonly priority?: "low" | "medium" | "high";
+}
+/**
+ * Parses a `cookie` request header into a prototype-less, frozen record (`__proto__` is just a
+ * name). Pairs are split on `;` only (never `,`) and trimmed; a pair without `=` or with an empty
+ * name is ignored; names are kept as sent (case-sensitive); a value wrapped in double quotes is
+ * unquoted, and percent-decoded when it contains `%` (a malformed sequence keeps the raw value).
+ * When a name repeats, the first occurrence wins (browsers send the most specific path first).
+ * Linear time, never throws.
+ */
+declare function parseCookieHeader(header: string | undefined): Readonly<Record<string, string>>;
+/**
+ * The `Set-Cookie` line of a cookie with the secure defaults
+ * (`Path=/; Secure; HttpOnly; SameSite=Lax`, overridable per cookie), in the order
+ * `name=value; Max-Age; Expires; Domain; Path; Secure; HttpOnly; SameSite; Partitioned; Priority`.
+ * The value is percent-encoded (see {@link encodeCookieValue}). Signing (`signed: true`) needs the
+ * secrets of the plugin: use `ctx.setCookie()` or `HttpPlugin.signCookie()`.
+ *
+ * ```ts
+ * serializeCookie('theme', 'dark', { maxAge: 86_400, httpOnly: false })
+ * // theme=dark; Max-Age=86400; Path=/; Secure; SameSite=Lax
+ * ```
+ *
+ * @throws TypeError for an invalid name, value or attribute, a `SameSite=None` or partitioned cookie
+ *   without `Secure`, a broken `__Secure-` / `__Host-` / `__Http-` / `__Host-Http-` prefix rule.
+ * @throws RangeError when `name=value` exceeds 4096 bytes, or `Domain` / `Path` 1024 bytes.
+ */
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+/**
+ * The `Set-Cookie` line clearing a cookie: `name=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT`
+ * plus `Domain`, `Path`, `Secure`, `HttpOnly`, `SameSite` and `Partitioned` (secure defaults merged
+ * with `options`), so that a prefixed cookie is cleared with valid attributes.
+ */
+declare function serializeClearCookie(name: string, options?: ClearCookieOptions): string;
+/**
+ * Parses a `Set-Cookie` line (attribute names are case-insensitive; the value is decoded like a
+ * request cookie). Used by `inject()` to fill `response.cookies`.
+ *
+ * @throws TypeError when the line has no `name=value` pair.
+ */
+declare function parseSetCookie(line: string): SetCookieInfo;
+/**
+ * A copy of the [Standard Schema v1](https://standardschema.dev) interface, flattened (no namespace,
+ * so the file stays erasable). Every compliant library (Zod, Valibot, ArkType, Effect Schema...)
+ * produces values assignable to {@link StandardSchemaV1}: no adapter and no dependency are needed.
+ */
+/** A schema implementing the Standard Schema v1 interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1Props<Input, Output>;
+}
+/** The Standard Schema properties. */
+interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+  /** The version number of the standard. */
+  readonly version: 1;
+  /** The vendor name of the schema library. */
+  readonly vendor: string;
+  /** Validates an unknown input value (synchronously or not). */
+  readonly validate: (value: unknown, options?: StandardSchemaV1Options | undefined) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+  /** Inferred types associated with the schema. */
+  readonly types?: StandardSchemaV1Types<Input, Output> | undefined;
+}
+/** Options of {@link StandardSchemaV1Props.validate}. */
+interface StandardSchemaV1Options {
+  /** Vendor-specific parameters. */
+  readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+/** Result of {@link StandardSchemaV1Props.validate}. */
+type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+/** Successful validation: the (possibly transformed) output value. */
+interface StandardSchemaV1SuccessResult<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+/** Failed validation. */
+interface StandardSchemaV1FailureResult {
+  readonly issues: readonly StandardSchemaV1Issue[];
+}
+/** One validation issue. */
+interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | StandardSchemaV1PathSegment)[] | undefined;
+}
+/** A path segment of an issue. */
+interface StandardSchemaV1PathSegment {
+  readonly key: PropertyKey;
+}
+/** Input and output types of a schema. */
+interface StandardSchemaV1Types<Input = unknown, Output = Input> {
+  readonly input: Input;
+  readonly output: Output;
+}
+/** The input type of a schema. */
+type InferSchemaInput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
+/** The output type of a schema (what handlers receive). */
+type InferSchemaOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+/** Whether `value` looks like a Standard Schema v1 (has a `~standard` object with a `validate` function). */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/** Response header values: a single value or several (`set-cookie`). */
+type HeaderValue = string | readonly string[];
+/** Options of {@link HttpException}. */
+interface HttpExceptionOptions extends ErrorOptions {
+  /** Headers added to the error response (`www-authenticate`, `retry-after`, `allow`...). */
+  readonly headers?: Readonly<Record<string, HeaderValue>>;
+}
+/** JSON body of an error response. */
+interface HttpErrorBody {
+  readonly statusCode: number;
+  /** Reason phrase of the status (`Not Found`). */
+  readonly error: string;
+  readonly message: string;
+  /** Structured details (validation issues...), omitted when absent. */
+  readonly details?: unknown;
+}
+/** One entry of the `details` of a validation error. */
+interface ValidationIssueDetail {
+  /** Dotted path of the invalid value inside the validated input (`user.email`, `items.0`), `''` for the root. */
+  readonly path: string;
+  readonly message: string;
+}
+/**
+ * An error carrying an HTTP status. Thrown from handlers, guards, interceptors or services, it is
+ * rendered as `{ statusCode, error, message, details? }` with its status and headers.
+ *
+ * ```ts
+ * throw new HttpException(409, 'Email already used', { field: 'email' })
+ * throw new NotFoundException(`User ${id} not found`)
+ * throw new UnauthorizedException('Token expired', undefined, { headers: { 'www-authenticate': 'Bearer' } })
+ * ```
+ *
+ * Invalid statuses (not an integer in 100–599) become `500`.
+ */
+declare class HttpException extends Error {
+  /** HTTP status of the response. */
+  readonly status: number;
+  /** Structured details rendered in the body (omitted when `undefined`). */
+  readonly details: unknown;
+  /** Headers added to the response. */
+  readonly headers: Readonly<Record<string, HeaderValue>>;
+  constructor(status: number, message?: string, details?: unknown, options?: HttpExceptionOptions);
+  /** The `statusCode` field of the body (alias of {@link status}). */
+  get statusCode(): number;
+  /** Body of the error response. Override it in a subclass to change the shape. */
+  toBody(): HttpErrorBody;
+}
+/** Whether `value` is an {@link HttpException} (also across duplicated package copies). */
+declare function isHttpException(value: unknown): value is HttpException;
+/** 400 Bad Request. */
+declare class BadRequestException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/**
+ * 400 Bad Request raised when an input fails its schema (`@Body(schema)`, `@Query(schema)`...).
+ * `details` lists the issues as `{ path, message }`; the raw Standard Schema issues are kept in
+ * {@link issues} for exception mappers.
+ */
+declare class ValidationException extends BadRequestException {
+  /** What was validated: `body`, `query`, `query "page"`, `param "id"`... */
+  readonly location: string;
+  readonly issues: readonly StandardSchemaV1Issue[];
+  constructor(location: string, issues: readonly StandardSchemaV1Issue[], options?: HttpExceptionOptions);
+}
+/** Converts a Standard Schema issue to `{ path, message }` (`path` dotted, `''` for the root). */
+declare function toIssueDetail(issue: StandardSchemaV1Issue): ValidationIssueDetail;
+/** 401 Unauthorized. */
+declare class UnauthorizedException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 403 Forbidden (also the response of a guard returning `false`). */
+declare class ForbiddenException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 404 Not Found. */
+declare class NotFoundException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 405 Method Not Allowed (pass the `allow` header in `options.headers`). */
+declare class MethodNotAllowedException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 409 Conflict. */
+declare class ConflictException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 410 Gone. */
+declare class GoneException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 413 Payload Too Large (request body above `bodyLimit`). */
+declare class PayloadTooLargeException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 415 Unsupported Media Type. */
+declare class UnsupportedMediaTypeException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 422 Unprocessable Entity. */
+declare class UnprocessableEntityException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 429 Too Many Requests (pass `retry-after` in `options.headers`). */
+declare class TooManyRequestsException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 500 Internal Server Error (its message is always sent, unlike unexpected errors). */
+declare class InternalServerErrorException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 501 Not Implemented. */
+declare class NotImplementedException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 502 Bad Gateway. */
+declare class BadGatewayException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 503 Service Unavailable. */
+declare class ServiceUnavailableException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** 504 Gateway Timeout. */
+declare class GatewayTimeoutException extends HttpException {
+  constructor(message?: string, details?: unknown, options?: HttpExceptionOptions);
+}
+/** Parsed query string (or `application/x-www-form-urlencoded` body): repeated keys become arrays. */
+type QueryRecord = Record<string, string | string[]>;
+/**
+ * Parses a query string (with or without the leading `?`) with `URLSearchParams` semantics (`+` is
+ * a space, malformed `%` sequences are kept as is, invalid UTF-8 becomes U+FFFD). A key present
+ * once maps to a string, a repeated key to an array of strings, in order. No nesting (`a[b]=1` is
+ * the key `a[b]`). The returned object has no prototype.
+ *
+ * `parseQuery('?tag=a&tag=b&page=2')` → `{ tag: ['a', 'b'], page: '2' }`
+ */
+declare function parseQuery(query: string): QueryRecord;
+/**
+ * Byte sizes (`1048576`, `'512kb'`, `'10 MiB'`, `'1.5gb'`) used by body and upload limits. This
+ * module is **pure** (no imports, no I/O): the compiler extension evaluates `@BodyLimit('10mb')` and
+ * `maxSize` options with it at build time.
+ *
+ * Units are case-insensitive and binary, like the `bytes` package used by Express:
+ * `b`, `kb`/`kib`/`k` = 1024, `mb`/`mib`/`m` = 1024², `gb`/`gib`/`g` = 1024³, `tb`/`tib`/`t` = 1024⁴.
+ */
+/**
+ * A size in bytes: a non-negative integer (`Infinity` disables the limit) or a string with a unit
+ * (`'512kb'`, `'10mb'`, `'1.5 GiB'`; `kb` = 1024 bytes).
+ */
+type ByteSize = number | string;
+/**
+ * Parses a {@link ByteSize}: `1024` → `1024`, `'10mb'` → `10485760`, `'1.5kb'` → `1536` (fractions
+ * are rounded down). Returns `undefined` for anything else (negative or fractional numbers,
+ * unknown units, `NaN`).
+ */
+declare function parseByteSize(value: unknown): number | undefined;
+/** Human-readable size for messages: `5 MiB`, `1.5 KiB`, `512 bytes`, `unlimited`. */
+declare function formatByteSize(bytes: number): string;
+/** Options of `@UploadedFile` (static: evaluated at build time). */
+interface UploadedFileOptions {
+  /**
+   * Answer 400 when no file is sent. Default: `true`, unless the parameter is optional
+   * (`file?: File`, `File | undefined`).
+   */
+  readonly required?: boolean;
+  /** Maximum size of the file (`5_000_000`, `'5mb'`; `kb` = 1024 bytes). Default: plugin `uploads.maxFileSize`. */
+  readonly maxSize?: ByteSize;
+  /**
+   * Accepted media types, as declared by the client: `'image/png'`, `'image/*'`, `'*\/*'`. Other
+   * types answer 415. Default: any.
+   */
+  readonly mimeTypes?: readonly string[];
+}
+/** Options of `@UploadedFiles` (static: evaluated at build time). */
+interface UploadedFilesOptions extends UploadedFileOptions {
+  /** Maximum number of files (413 above). Default: plugin `uploads.maxFiles`. */
+  readonly maxFiles?: number;
+}
+/** Plugin-wide upload limits (`HttpPlugin.configure({ uploads })`). */
+interface UploadLimits {
+  /** Default maximum size of one file (`maxSize` of upload parameters). Default: `'10mb'`. */
+  readonly maxFileSize?: ByteSize;
+  /** Default maximum number of files of `@UploadedFiles` (and of multipart bodies of other routes). Default: `10`. */
+  readonly maxFiles?: number;
+  /** Maximum number of parts (text fields and files) of a multipart body (413 above). Default: `1000`. */
+  readonly maxParts?: number;
+  /** Maximum size of one text field of a multipart body (413 above). Default: `'1mb'`. */
+  readonly maxFieldSize?: ByteSize;
+}
+/**
+ * Reads uploaded files from the context (`ctx.files`) in generated `invoke` functions
+ * (`@UploadedFile('avatar') avatar: File` → `uploads.file(ctx, 'avatar')`). `field` `undefined`
+ * means any field. Limits were enforced while the body was read; these helpers check presence.
+ */
+interface Uploads {
+  /** The file of `field`; 400 `Missing file "field"` when absent. */
+  file(ctx: HttpContext, field: string | undefined): File;
+  /** The file of `field`, `undefined` when absent. */
+  optionalFile(ctx: HttpContext, field: string | undefined): File | undefined;
+  /** The files of `field` (at least one); 400 `Missing files "field"` when none. */
+  files(ctx: HttpContext, field: string | undefined): File[];
+  /** The files of `field`, possibly none. */
+  optionalFiles(ctx: HttpContext, field: string | undefined): File[];
+}
+/** The helpers of the generated code (`import { uploads } from '@znight/http'`). */
+declare const uploads: Uploads;
+declare const requestIdBrand: unique symbol;
+/** Why `ctx.signal` aborted: the client left, the server shuts down, or an SSE stream reached its `maxDuration`. */
+type RequestAbortKind = "client" | "shutdown" | "expired";
+/**
+ * The reason of an aborted `ctx.signal`. Named `AbortError`, what `fetch`, `node:timers/promises`
+ * and most libraries check.
+ */
+declare class RequestAbortedError extends Error {
+  override readonly name = "AbortError";
+  /** `client`: disconnected; `shutdown`: the server stops; `expired`: an SSE stream reached its `maxDuration`. */
+  readonly kind: RequestAbortKind;
+  constructor(kind: RequestAbortKind);
+}
+/**
+ * Identifier of the current request: the incoming `x-request-id` header (see the plugin option
+ * `requestIdHeader`) or a generated UUID. Injectable in request-scoped providers.
+ */
+type RequestId = string & {
+  readonly [requestIdBrand]: true;
+};
+/** The route that matched a request. */
+interface HttpRouteInfo {
+  /** Route method (`GET`...; the concrete method for `@All` routes). */
+  readonly method: string;
+  /** Route pattern including the plugin prefix (`/api/users/:id`). */
+  readonly path: string;
+  /** Controller provider token. */
+  readonly controller: Token;
+  /** Handler method name. */
+  readonly handler: string;
+  /**
+   * Effective route metadata (`createRouteDecorator`): the controller's entries, except those of a
+   * group the route decides itself, then the route's entries (the nearest decision wins).
+   */
+  readonly meta: Readonly<Record<string, unknown>>;
+}
+declare module "@znight/core" {
+  /** Custom parameter decorators (`createParamDecorator`) resolve HTTP parameters from the {@link HttpContext}. */
+  interface ParamContexts {
+    http: HttpContext;
+  }
+}
+/**
+ * Adapter-neutral view of the current HTTP request, shared by guards, interceptors, exception
+ * mappers and handlers (`@Ctx()`), and injectable in request-scoped providers.
+ */
+interface HttpContext {
+  readonly requestId: RequestId;
+  /** Upper-case method. */
+  readonly method: string;
+  /** Raw request target (`/users/a%20b?page=2`). */
+  readonly url: string;
+  /** Raw path, without query string (`/users/a%20b`). */
+  readonly path: string;
+  /** Decoded route parameters (`*` holds the part matched by a trailing wildcard). */
+  readonly params: Readonly<Record<string, string>>;
+  /** Decoded query string (repeated keys → arrays), parsed on first access. */
+  readonly query: Readonly<QueryRecord>;
+  /** Request headers, lower-case names. */
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  /**
+   * Parsed body. Populated before the interceptors for routes declaring `@Body()` or upload
+   * parameters (and after {@link parseBody} resolved otherwise); `undefined` until then and for
+   * empty bodies. Forms (urlencoded and multipart) are records of their text fields.
+   */
+  readonly body: unknown;
+  /**
+   * Files of a `multipart/form-data` body by field name, in body order (standard `File` objects,
+   * held in memory). Populated with {@link body}; empty for other bodies.
+   */
+  readonly files: Readonly<Record<string, readonly File[]>>;
+  /** The matched route, `undefined` for unmatched requests (404/405). */
+  readonly route: HttpRouteInfo | undefined;
+  /** Per-request storage for guards, interceptors and handlers (`ctx.state.set('user', user)`). */
+  readonly state: Map<string | symbol, unknown>;
+  /** Native request of the adapter (`IncomingMessage`, `FastifyRequest`, Express `Request`, Web `Request`). */
+  readonly request: unknown;
+  /** Native response of the adapter (`ServerResponse`, `FastifyReply`, Express `Response`, Hono `Context`). */
+  readonly response: unknown;
+  /** Adapter name (`node`, `fastify`, `express`, `hono`). */
+  readonly adapter: string;
+  /**
+   * Client address, when the adapter knows it. With the plugin option `trustProxy`, the address
+   * found in `x-forwarded-for` behind the trusted proxies; otherwise the adapter's address (the
+   * socket peer, or what Fastify / Express derive from their own proxy settings).
+   */
+  readonly ip: string | undefined;
+  /**
+   * `https` when the connection uses TLS, or, behind a trusted proxy (`trustProxy`), when the
+   * leftmost `x-forwarded-proto` says so; `http` otherwise.
+   */
+  readonly protocol: "http" | "https";
+  /** Headers added to the response, whatever its outcome (errors included). */
+  readonly responseHeaders: Readonly<Record<string, HeaderValue>>;
+  /** A request header (case-insensitive name). */
+  header(name: string): string | undefined;
+  /** Sets a response header (case-insensitive name), sent with success and error responses. */
+  setHeader(name: string, value: HeaderValue): void;
+  /** Appends a response header value (`set-cookie`...). */
+  appendHeader(name: string, value: string): void;
+  /**
+   * Request cookies (`cookie` header), parsed on first access: decoded values, the first occurrence
+   * of a name wins. A prototype-less, frozen record.
+   */
+  readonly cookies: Readonly<Record<string, string>>;
+  /**
+   * The verified value of a signed cookie (`@SignedCookie`), `undefined` when it is absent, tampered
+   * or signed with a key that is no longer in `cookies.secrets`. Verified once per name.
+   *
+   * @throws Error when the plugin option `cookies.secrets` is not set.
+   */
+  signedCookie(name: string): string | undefined;
+  /**
+   * Sets a cookie on the response, whatever its outcome (errors, redirects included), with the
+   * secure defaults (`Path=/; Secure; HttpOnly; SameSite=Lax`, see the plugin option
+   * `cookies.defaults`). A later cookie with the same name, domain and path replaces this one; a
+   * cookie of the same key in an `HttpResponse` (`withCookie`) wins over it. Everything is validated
+   * now (name, value, attributes, prefixes, size), so the stack trace points to the faulty call.
+   *
+   * @throws TypeError / RangeError for an invalid cookie; Error once the response headers were sent
+   *   (a running event stream).
+   */
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  /**
+   * Clears a cookie (`Max-Age=0`, with the same domain and path, and the defaults: a `__Host-`
+   * cookie is cleared with valid attributes).
+   *
+   * @throws like {@link setCookie}.
+   */
+  clearCookie(name: string, options?: ClearCookieOptions): void;
+  /** Cookies set on this response so far (`setCookie` / `clearCookie`), in order. */
+  readonly responseCookies: readonly ResponseCookie[];
+  /**
+   * Aborted when the client disconnects before the response was written, when the response body is
+   * cancelled, or when the server closes an event stream (shutdown, `maxDuration`); never after a
+   * normal completion. The reason is a {@link RequestAbortedError}. Pass it to the work the request
+   * starts (`fetch(url, { signal: ctx.signal })`, `setTimeout(ms, v, { signal })`). Created on first
+   * access.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Reads and parses the body (once): JSON (`application/json`, `+json`), text (`text/*`), forms
+   * (`application/x-www-form-urlencoded` and `multipart/form-data` → record of the text fields,
+   * repeated names as arrays; files in {@link files}), raw bytes otherwise; `undefined` when empty.
+   * Fails with 400 (malformed), 413 (body or upload limits) or 415 (unsupported encoding, refused
+   * file type, non-multipart body on an upload route).
+   */
+  parseBody(): Promise<unknown>;
+  /** The raw body bytes (once; shared with {@link parseBody}), e.g. to check a webhook signature. */
+  rawBody(): Promise<Uint8Array>;
+  /**
+   * The request body as a Web stream, read as it arrives (nothing is buffered): the escape hatch
+   * for large uploads (`PUT /files/:name` piped to disk or object storage). The body limit of the
+   * route still applies (`@BodyLimit`, `Infinity` to disable): past it the stream errors with a
+   * `PayloadTooLargeException` (413). Exclusive with {@link rawBody} / {@link parseBody}: throws when
+   * the body was already read (routes with `@Body()` or upload parameters read it before the
+   * handler).
+   */
+  bodyStream(): ReadableStream<Uint8Array>;
+}
+/** Route methods. `ALL` registers the route for GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS. */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
+/**
+ * Where a handler parameter comes from (`file` / `files`: `@UploadedFile` / `@UploadedFiles`, the
+ * `name` being the multipart field; `cookie` / `signedCookie`: `@Cookie` / `@SignedCookie`, the
+ * `name` being the cookie name).
+ */
+type HttpParamSource = "param" | "query" | "body" | "headers" | "request" | "response" | "context" | "file" | "files" | "cookie" | "signedCookie" | "custom";
+/** A handler parameter (informational: extraction, coercion and validation happen in `invoke`). */
+interface HttpParamDefinition {
+  /** Position in the handler signature. */
+  readonly index: number;
+  readonly source: HttpParamSource;
+  /** Parameter / query key / header name (lower case) / multipart field. Absent: the whole object (every field). */
+  readonly name?: string;
+  /** Serialised declared type (`number`, `string[]`, `'asc' | 'desc'`...). */
+  readonly type?: string;
+  readonly optional?: boolean;
+  /** `true` when the value is validated with a schema. */
+  readonly schema?: boolean;
+}
+/**
+ * Files accepted by an upload parameter (`@UploadedFile` / `@UploadedFiles`). The plugin enforces
+ * these rules while the multipart body is read; the presence of required files is checked by
+ * `invoke` (the `uploads` helpers).
+ */
+interface HttpUploadDefinition {
+  /** Multipart field. Absent: files of any field. */
+  readonly field?: string;
+  /** `true` for `@UploadedFiles` (several files). */
+  readonly multiple?: boolean;
+  /** `true` when a file must be sent (informational, checked by `invoke`). */
+  readonly required?: boolean;
+  /** Maximum size of each file in bytes (`Infinity`: no limit). Default: plugin `uploads.maxFileSize`. */
+  readonly maxSize?: number;
+  /** Maximum number of files (`@UploadedFiles`). Default: plugin `uploads.maxFiles` (1 for `@UploadedFile`). */
+  readonly maxFiles?: number;
+  /** Accepted media types (`image/png`, `image/*`), compared with the type declared by the client. */
+  readonly mimeTypes?: readonly string[];
+}
+/** Options of an `@Sse` route (`HttpRouteDefinition.sse`). */
+interface HttpSseDefinition {
+  /** Heartbeat interval in ms (≥ 1 000); `0` disables it. Absent: the plugin option `sse.heartbeat`. */
+  readonly heartbeat?: number;
+  /** `retry` sent first (ms). Absent: the plugin option `sse.retry`. */
+  readonly retry?: number;
+  /** The stream ends gracefully after this many ms (≥ 1 000). */
+  readonly maxDuration?: number;
+}
+/** A route: one decorated method of a controller. */
+interface HttpRouteDefinition {
+  readonly method: HttpMethod;
+  /** Path of the route decorator, normalised (`/:id`). */
+  readonly path: string;
+  /** `joinPaths(controller.basePath, path)` (without the plugin `prefix`). */
+  readonly fullPath: string;
+  /** Name of the handler method. */
+  readonly handler: string;
+  /** `@HttpCode(status)`. */
+  readonly status?: number;
+  /** `@Header(name, value)` entries (names in lower case). */
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Route metadata (`createRouteDecorator`), merged over the controller metadata at runtime, one
+   * decision per group: the route's entry of a group replaces the controller's entries of that group
+   * (see {@link HttpMetadata.groups}).
+   */
+  readonly meta: Readonly<Record<string, unknown>>;
+  /** Route guards (provider tokens), run after global and controller guards. */
+  readonly guards: readonly Token[];
+  /** Route interceptors (provider tokens), innermost. */
+  readonly interceptors: readonly Token[];
+  readonly params: readonly HttpParamDefinition[];
+  /**
+   * `@BodyLimit` (route or controller): maximum body size in bytes (`Infinity`: no limit). Default:
+   * the plugin `bodyLimit`, or for upload routes the sum of the file limits plus `bodyLimit`.
+   */
+  readonly bodyLimit?: number;
+  /**
+   * Upload rules (one per `@UploadedFile` / `@UploadedFiles` parameter). Routes with uploads parse
+   * `multipart/form-data` bodies before the interceptors and answer 415 to other non-empty bodies.
+   */
+  readonly uploads?: readonly HttpUploadDefinition[];
+  /** `true` when the handler takes `@Res()` and writes the response itself. */
+  readonly rawResponse?: boolean;
+  /**
+   * `@Sse` route (GET only): the handler result (an `AsyncIterable`, an `Iterable` or a
+   * `ReadableStream` of `SseEvent`) is served as an event stream; an `HttpResponse` or a Web
+   * `Response` is sent as usual. `{}` without options.
+   */
+  readonly sse?: HttpSseDefinition;
+  /**
+   * Provider classes resolving custom parameters (`ParamResolver`, RFC 0010), in order of first use:
+   * the plugin resolves them in the request scope and passes the instances to `invoke` as `x`
+   * (`x[i]` is the instance of `paramResolvers[i]`). Absent when the route has none.
+   */
+  readonly paramResolvers?: readonly Token[];
+  /**
+   * Calls the handler: extracts, coerces and validates every argument from the context (custom
+   * parameters included), then calls the method on the controller instance. May return a promise.
+   * `resolvers` is passed when the route has {@link paramResolvers}.
+   */
+  readonly invoke: (controller: any, ctx: HttpContext, resolvers?: any) => unknown;
+}
+/** A controller: a provider whose methods are routes. */
+interface HttpControllerDefinition {
+  /** Provider token of the controller class. */
+  readonly token: Token;
+  /** Normalised base path (`/users`, `/` when absent). */
+  readonly basePath: string;
+  /** Controller guards (provider tokens). */
+  readonly guards: readonly Token[];
+  /** Controller interceptors (provider tokens). */
+  readonly interceptors: readonly Token[];
+  /** Controller metadata (`createRouteDecorator` on the class). */
+  readonly meta: Readonly<Record<string, unknown>>;
+  readonly routes: readonly HttpRouteDefinition[];
+}
+/** A route decorator group (`createRouteDecorator(key, { group, required })`). */
+interface HttpRouteGroupDefinition {
+  /** Keys of the decorators of the group, sorted. */
+  readonly keys: readonly string[];
+  /** Every route must carry a decision of the group. */
+  readonly required: boolean;
+}
+/** `metadata.extensions.http`. */
+interface HttpMetadata {
+  readonly controllers: readonly HttpControllerDefinition[];
+  /**
+   * Route decorator groups that need to be known at runtime (required, holding several keys, or
+   * named differently from their key): group → `{ keys, required }`. A key belongs to one group at
+   * most; a key listed nowhere is its own group. Absent when no group needs it.
+   */
+  readonly groups?: Readonly<Record<string, HttpRouteGroupDefinition>>;
+}
+declare module "@znight/core" {
+  interface ZnightExtensionsMetadata {
+    readonly http?: HttpMetadata;
+  }
+}
+/** 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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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). */
+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? }`.
+ */
+declare function Controller(_pathOrOptions?: string | ControllerOptions): ClassMarker;
+/** `GET` route. `path` (static) is relative to the controller path; default: the controller path. */
+declare function Get(_path?: string): MethodMarker;
+/** `POST` route (default status 201). */
+declare function Post(_path?: string): MethodMarker;
+/** `PUT` route. */
+declare function Put(_path?: string): MethodMarker;
+/** `PATCH` route. */
+declare function Patch(_path?: string): MethodMarker;
+/** `DELETE` route. */
+declare function Delete(_path?: string): MethodMarker;
+/** `HEAD` route (`GET` routes already answer `HEAD` requests). */
+declare function Head(_path?: string): MethodMarker;
+/** `OPTIONS` route (paths without one answer `OPTIONS` with `204` and an `allow` header). */
+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). */
+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`).
+ */
+declare function Sse(path?: string, options?: SseOptions): MethodMarker;
+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).
+ */
+declare function Param(): ParameterMarker;
+declare function Param(name: string, schema?: StandardSchemaV1): ParameterMarker;
+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).
+ */
+declare function Query(): ParameterMarker;
+declare function Query(name: string, schema?: StandardSchemaV1): ParameterMarker;
+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).
+ */
+declare function Cookie(): ParameterMarker;
+declare function Cookie(name: string, schema?: StandardSchemaV1): ParameterMarker;
+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).
+ */
+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...).
+ */
+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.
+ */
+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? }`.
+ */
+declare function UploadedFile(field?: string, options?: UploadedFileOptions): ParameterMarker;
+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? }`.
+ */
+declare function UploadedFiles(field?: string, options?: UploadedFilesOptions): ParameterMarker;
+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).
+ */
+declare function BodyLimit(_size: ByteSize): ClassMarker & MethodMarker;
+/** Injects the native request of the adapter (escape hatch; the compiler warns). */
+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.
+ */
+declare function Res(): ParameterMarker;
+/** Injects the {@link HttpContext} of the request. */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+}
+/**
+ * Anything that carries effective route metadata: the {@link HttpContext} of a request, and the
+ * contexts of other transports that reuse route decorators (a GraphQL resolver context, a WebSocket
+ * gateway context). {@link RouteDecorator.get} reads `route.meta[key]`; nothing else is required.
+ *
+ * ```ts
+ * const carrier: RouteMetaCarrier = { route: { meta: { roles: ['admin'] } } }
+ * Roles.get(carrier) // ['admin']
+ * ```
+ */
+interface RouteMetaCarrier {
+  /** The matched route (or field, or handler), `undefined` when there is none. */
+  readonly route?: {
+    readonly meta: Readonly<Record<string, unknown>>;
+  } | undefined;
+}
+/** 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. Accepts any {@link RouteMetaCarrier}: an
+   * {@link HttpContext}, or the context of another transport exposing `route.meta`.
+   */
+  get(ctx: RouteMetaCarrier): 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? }`.
+ */
+declare function createRouteDecorator<T = true>(key: string, options?: RouteDecoratorOptions): RouteDecorator<T>;
+/**
+ * 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;
+}
+/**
+ * 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())
+ * }
+ * ```
+ */
+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 the boot check reports problems. */
+type EnforcementMode = "error" | "warn";
+/** 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[];
+  /** `'websocket'` for a WebSocket upgrade route (RFC 0003): a gateway of `@znight/websocket`. */
+  readonly upgrade?: "websocket";
+}
+/**
+ * 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.
+ */
+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>;
+  /**
+   * Runs a WebSocket handshake in memory (RFC 0003, `WebSocketPlugin.connect()`): the same pipeline
+   * as an upgrade request of the adapter (guards, hooks, the route's checks), without socket. The
+   * transport receives `{ kind: 'memory', peer }`. Resolves with the refusal, or `undefined` once
+   * the connection was accepted. Available after `onBootstrap`.
+   */
+  upgradeInMemory(request: InjectRequest, native: MemoryUpgrade): Promise<InjectResponse | undefined>;
+  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[];
+  /**
+   * Maximum body size of this route (`'100kb'`, `1048576`, `Infinity`), with the grammar of the
+   * `HttpPlugin` option `bodyLimit`, which it replaces for this route only (lower or higher, like
+   * `@BodyLimit` on a controller route). Past it, reading the body answers 413. Default: the
+   * `HttpPlugin` option.
+   */
+  readonly bodyLimit?: ByteSize;
+}
+/** 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[];
+  /**
+   * Called once when `HttpPlugin` starts draining (its `onStop`, whatever the plugin order), after
+   * it stopped accepting connections and started closing its event streams: end the long-lived
+   * responses `HttpPlugin` does not know of (a stream another server produced), so that the drain
+   * does not wait for them until `drainTimeoutMs`. Requests still in flight are served. The drain
+   * waits for a returned promise too (within `drainTimeoutMs`); a failure is logged.
+   */
+  onHttpDrain?(): void | Promise<void>;
+  /**
+   * WebSocket upgrade routes of the plugin (RFC 0003, `@znight/websocket`): see
+   * {@link PluginHttpUpgrades}. Called once in `onBootstrap`, after `httpRoutes()`.
+   */
+  httpUpgrades?(context: PluginHttpUpgradesContext): PluginUpgrades;
+}
+/**
+ * The upgrade of a `node:http` server (`'upgrade'` event): every adapter built on `node:http`
+ * (`node`, `express`, `fastify`, `hono` on Node.js), on Node.js and on Bun.
+ */
+interface NodeUpgrade {
+  readonly kind: "node";
+  /** The `IncomingMessage` of the handshake. */
+  readonly request: unknown;
+  /** The `net.Socket` (a `Duplex`) of the connection. */
+  readonly socket: unknown;
+  /** The first bytes after the handshake headers. */
+  readonly head: Uint8Array;
+}
+/** The upgrade of a `Bun.serve()` server (`honoAdapter()` on Bun). */
+interface BunUpgrade {
+  readonly kind: "bun";
+  /** The Fetch `Request` of the handshake. */
+  readonly request: Request;
+  /** The `Bun.serve()` server (`server.upgrade(request, { data, headers })`). */
+  readonly server: unknown;
+}
+/** An in-memory upgrade (`HttpPlugin.upgradeInMemory()`, tests): `peer` belongs to the caller. */
+interface MemoryUpgrade {
+  readonly kind: "memory";
+  readonly peer: unknown;
+}
+/** The native side of an upgrade request, completed by a transport. */
+type NativeUpgrade = NodeUpgrade | BunUpgrade | MemoryUpgrade;
+/** What {@link PluginUpgradeRoute.accept} receives to complete the handshake. */
+interface PendingUpgrade {
+  readonly native: NativeUpgrade;
+  /**
+   * Headers of the `101` response: the headers and cookies the guards set on the context, the
+   * request id and the security headers are not included (they are HTTP response headers); read
+   * once, when the transport completes the handshake.
+   */
+  readonly headers: Readonly<Record<string, HeaderValue>>;
+  /**
+   * The handshake timed out and was answered `408`: the transport must not complete it. Check it
+   * after every `await`, right before completing the handshake.
+   */
+  readonly expired: boolean;
+  /**
+   * Keeps the request scope (and the in-flight count of `HttpPlugin`) open until `closed`
+   * settles: the connection lives in the scope of its handshake. Call it once, after the transport
+   * completed the handshake.
+   */
+  hold(closed: Promise<unknown>): void;
+}
+/**
+ * A route answering upgrade requests (`GET` with `upgrade: websocket`), declared by another plugin
+ * through {@link PluginHttpUpgrades.httpUpgrades}.
+ */
+interface PluginUpgradeRoute {
+  /** Path relative to the `HttpPlugin` prefix, with the route grammar (`/chat`, `/docs/:docId`). */
+  readonly path: string;
+  /** Name of the route (the gateway), shown in `HttpPlugin.routes`, logs and errors. */
+  readonly name: string;
+  /** `ctx.route.controller` during the handshake (the gateway token). Default: the plugin name. */
+  readonly owner?: Token;
+  /** Route metadata (`ctx.route.meta`), one entry per group, checked at boot like plugin routes. */
+  readonly meta?: readonly RouteMetaEntry[];
+  /** Guards of the handshake (classes, instances or provider tokens), after the global guards. */
+  readonly guards?: readonly (GuardRef | Token)[];
+  /** Time the handshake gets before it is answered `408` (ms). Default: none. */
+  readonly timeoutMs?: number;
+  /**
+   * Cheap checks before the guards (origin, subprotocols, capacity), after the protocol checks of
+   * RFC 6455. Throw an `HttpException` to refuse.
+   */
+  precheck?(ctx: HttpContext): void | Promise<void>;
+  /** After the guards: take the connection. Throw an `HttpException` to refuse. */
+  accept(ctx: HttpContext, upgrade: PendingUpgrade): void | Promise<void>;
+}
+/** What {@link PluginHttpUpgrades.httpUpgrades} returns. */
+interface PluginUpgrades {
+  readonly routes: readonly PluginUpgradeRoute[];
+  /**
+   * Server-wide settings of the `websocket` option of `Bun.serve()` (`maxPayloadLength`,
+   * `idleTimeout`, `backpressureLimit`, `sendPings`, `perMessageDeflate`...), used by adapters
+   * serving with `Bun.serve()`. The handlers are set by `HttpPlugin`: they dispatch every event to
+   * the `data` given to `server.upgrade()`, a {@link BunSocketHandlers}.
+   */
+  readonly bunWebSocket?: Readonly<Record<string, unknown>>;
+}
+/** What {@link PluginHttpUpgrades.httpUpgrades} receives. */
+interface PluginHttpUpgradesContext extends PluginHttpRoutesContext {
+  /** Name of the adapter (`node`, `fastify`...). */
+  readonly adapter: string;
+  /**
+   * The native upgrades the adapter produces (`node`: a `node:http` server, `bun`: `Bun.serve()`),
+   * `undefined` when the adapter cannot upgrade connections.
+   */
+  readonly upgrades: "node" | "bun" | undefined;
+}
+/**
+ * Implemented, next to {@link PluginHttpRoutes}, by a plugin that accepts WebSocket connections
+ * (`@znight/websocket`). `HttpPlugin` calls `httpUpgrades()` once in its `onBootstrap`, after
+ * `httpRoutes()`, whatever the plugin order, and asks its adapter to route the matching upgrade
+ * requests to the pipeline. `onHttpDrain()` is where the plugin closes its connections.
+ */
+interface PluginHttpUpgrades {
+  httpUpgrades(context: PluginHttpUpgradesContext): PluginUpgrades;
+}
+/**
+ * The `data` a transport gives to `server.upgrade()` on `Bun.serve()`: `HttpPlugin` dispatches
+ * every event of the socket to it.
+ */
+interface BunSocketHandlers {
+  open(ws: unknown): void;
+  message(ws: unknown, message: string | Uint8Array): void;
+  close(ws: unknown, code: number, reason: string): void;
+  drain(ws: unknown): void;
+  pong?(ws: unknown): void;
+}
+/** What `HttpPlugin` gives to {@link AdapterUpgrades.enable}. */
+interface UpgradeHandlerOptions {
+  /** Whether an upgrade request to the raw `path` (no query string) is for Znight. */
+  match(path: string): boolean;
+  /**
+   * Runs the handshake through the pipeline. Resolves with the refusal to write (an HTTP response),
+   * or `undefined` once the transport took the connection. Never rejects.
+   */
+  handle(request: AdapterRequest, native: NodeUpgrade | BunUpgrade): Promise<AdapterReply | undefined>;
+  /** The `websocket` option of `Bun.serve()` (settings and dispatching handlers), Bun adapters only. */
+  readonly bunWebSocket: Readonly<Record<string, unknown>>;
+}
+/** The optional upgrade capability of an adapter (RFC 0003 §8.2.3). */
+interface AdapterUpgrades {
+  /** The native upgrades the adapter produces. */
+  readonly kind: "node" | "bun";
+  /** Called once, before `listen()`, when the application has upgrade routes. */
+  enable(options: UpgradeHandlerOptions): void;
+}
+/** A request, as seen by the plugin. */
+interface AdapterRequest {
+  /** Upper-case method. */
+  readonly method: string;
+  /** Raw request target: path and query string, percent-encoded (`/users/a%20b?page=2`). */
+  readonly url: string;
+  /** Request headers with lower-case names (repeated headers joined with `, `). */
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  /**
+   * Client address, when known: the socket peer, or the address the server framework derives from
+   * its own proxy settings (Fastify `trustProxy`, Express `trust proxy`). This is `ctx.ip` unless
+   * the plugin option `trustProxy` is set.
+   */
+  readonly ip: string | undefined;
+  /**
+   * Address of the socket peer, **never** taken from headers: where the plugin starts walking
+   * `x-forwarded-for` with `trustProxy`. Optional (`ip` is used without it); the built-in adapters
+   * set it.
+   */
+  readonly remoteAddress?: string | undefined;
+  /** `true` when the connection uses TLS (`ctx.protocol` without a trusted proxy). Optional. */
+  readonly encrypted?: boolean;
+  /** Native request object (`@Req()`). */
+  readonly raw: unknown;
+  /** Native response object (`@Res()`). */
+  readonly rawResponse: unknown;
+  /**
+   * Reads the whole body (once). Rejects with a `PayloadTooLargeException` when it exceeds `limit`
+   * bytes (checked on `content-length` first, then while reading).
+   */
+  readBody(limit: number): Promise<Uint8Array>;
+  /**
+   * The body as a Web stream, read as the consumer pulls it (once; exclusive with `readBody`). It
+   * errors with a `PayloadTooLargeException` past `limit` bytes (`content-length` checked first) and
+   * with a `BadRequestException` when the client aborts. Cancelling it discards the rest of the body
+   * without closing the connection before the response is written. Optional: without it the plugin
+   * streams the result of `readBody` (multipart uploads are then buffered before being parsed).
+   */
+  streamBody?(limit: number): ReadableStream<Uint8Array>;
+  /**
+   * Whether the request has a body, asked only when its headers declare none (neither
+   * `content-length` nor `transfer-encoding`: Web `Request`s built in memory). Return `false` for
+   * requests read from an HTTP/1.1 connection (without those headers they have no body). Optional:
+   * no body is assumed otherwise.
+   */
+  hasBody?(): boolean;
+  /** Status written by a handler that took over the response with `@Res()`, when known. */
+  rawStatus?(): number | undefined;
+  /**
+   * Registers a listener called once when the client disconnects before the response was fully
+   * written. When it already happened, the listener is called on the next microtask. Never called
+   * after a complete response. Optional: without it, `ctx.signal` only aborts when the response
+   * body is cancelled or an event stream is closed by the server.
+   */
+  onAbort?(listener: () => void): void;
+}
+/**
+ * Body of a reply: bytes, a stream or nothing. Adapters MUST either read a stream to its end or
+ * cancel it (client disconnected, response not sent...): the request scope and the in-flight count
+ * are released then. A `Blob` is sent with its size; the plugin itself never passes one: it sends
+ * files as a stream reading the `Blob`, given in {@link AdapterReply.blob}.
+ */
+type ReplyBody = Uint8Array | ReadableStream<Uint8Array> | Blob | null;
+/** A response computed by the plugin, written by the adapter. */
+interface AdapterReply {
+  readonly status: number;
+  /** Response headers, lower-case names (validated: every name and value can be sent). */
+  readonly headers: Readonly<Record<string, HeaderValue>>;
+  /** `null` for HEAD requests and bodyless statuses (headers such as `content-length` are kept). */
+  readonly body: ReplyBody;
+  /**
+   * The text `body` holds encoded as UTF-8, for a body serialised from a string (JSON, text).
+   * Adapters writing strings MAY send it instead of `body`, which writes the same bytes: Node.js then
+   * writes the headers and the body at once (bytes take a second write).
+   */
+  readonly text?: string;
+  /**
+   * The `Blob` (file) that `body` streams, for adapters able to send it natively (`sendfile`, exact
+   * length: `new Response(blob)` on `Bun.serve()`). An adapter sending it instead of reading `body`
+   * MUST cancel `body` once the server holds the blob (file opened): that releases the request
+   * scope, which may delete the file. Headers (`content-length`...) are the same either way.
+   */
+  readonly blob?: Blob;
+  /** The handler wrote the response itself through `@Res()`: write nothing. */
+  readonly raw?: boolean;
+  /**
+   * The body is a long-lived event stream (a streamed `text/event-stream` body: `@Sse`,
+   * `HttpResponse.sse()`, a proxied `fetch()` response...). Adapters MUST send the headers without
+   * waiting for the first chunk (a quiet stream may send nothing for a while), MUST NOT apply idle or
+   * inactivity timeouts to the response while it is sent, and MUST write each chunk as soon as it is
+   * read (no buffering, no compression).
+   */
+  readonly eventStream?: boolean;
+}
+/** Handles one request. Never rejects: errors are already mapped to a reply. */
+type AdapterHandler = (request: AdapterRequest) => Promise<AdapterReply>;
+/**
+ * Handles requests no route matched (`404`/`405`, automatic `OPTIONS`) and errors raised by the
+ * server framework before a route handler ran (`error`, e.g. a malformed URL). Never rejects.
+ */
+type FallbackHandler = (request: AdapterRequest, error?: unknown) => Promise<AdapterReply>;
+/** A concrete route to register (the plugin expands `ALL` and adds `HEAD` for `GET` routes). */
+interface AdapterRoute {
+  readonly method: Exclude<HttpMethod, "ALL">;
+  /** Parsed full path (plugin prefix included). Translate it with the helpers of `@znight/http/path`. */
+  readonly path: RoutePath;
+  readonly handler: AdapterHandler;
+}
+/** Address of a listening server. Converts to its URL (`String(address)`). */
+interface HttpServerAddress {
+  /** Host the server is bound to (`0.0.0.0`, `::`, `127.0.0.1`...). */
+  readonly host: string;
+  readonly port: number;
+  /** `IPv4` or `IPv6`. */
+  readonly family: string;
+  /** Base URL usable by clients (`http://127.0.0.1:3000`; wildcard hosts become loopback addresses). */
+  readonly url: string;
+  toString(): string;
+}
+/** A request for {@link HttpAdapter.inject} (in-memory, no network). */
+interface InjectRequest {
+  readonly method: string;
+  /** Path and optional query string (`/users?page=2`). */
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Request body: a string or bytes are sent as is (`text/plain` / `application/octet-stream` when
+   * no `content-type` is given), a `FormData` as `multipart/form-data` (files included), a `Blob` /
+   * `File` with its type, anything else as JSON (`application/json`).
+   */
+  readonly body?: unknown;
+  /** Query parameters appended to `url`. */
+  readonly query?: Readonly<Record<string, string | readonly string[]>>;
+  /**
+   * Request cookies (name → value), sent in a `cookie` header after any `cookie` header of
+   * `headers`. Values are encoded like the values of `serializeCookie`, so a value read from
+   * `response.cookies` can be sent back as is (signed values included).
+   */
+  readonly cookies?: Readonly<Record<string, string>>;
+  /**
+   * Cookies signed by `HttpPlugin` with its first secret (`cookies.secrets`) and merged into
+   * `cookies` before dispatch: the way to send a valid `@SignedCookie`. Adapters never receive this
+   * field.
+   */
+  readonly signedCookies?: Readonly<Record<string, string>>;
+}
+/** A request for {@link HttpAdapter.injectStream}: an {@link InjectRequest} that can be aborted. */
+interface InjectStreamRequest extends InjectRequest {
+  /** Aborting it disconnects the client (like cancelling the response body). */
+  readonly signal?: AbortSignal;
+}
+/**
+ * A request for `HttpPlugin.injectStream()` / `injectSse()`: an {@link InjectStreamRequest} whose
+ * method defaults to `GET`.
+ */
+type InjectStreamOptions = Omit<InjectStreamRequest, "method"> & {
+  readonly method?: string;
+};
+/** The response of {@link HttpAdapter.inject}. */
+interface InjectResponse {
+  readonly status: number;
+  /**
+   * Lower-case header names; repeated headers are joined with `, `, except `set-cookie`: an array
+   * with one entry per cookie (cookie values may contain `, `).
+   */
+  readonly headers: Record<string, string | string[]>;
+  /** Body decoded as UTF-8. */
+  readonly body: string;
+  /** Raw body bytes (binary downloads). */
+  readonly bytes: Uint8Array;
+  /** `JSON.parse(body)`. */
+  json<T = unknown>(): T;
+  /** `set-cookie` parsed, by cookie name (the last one wins). */
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+}
+/**
+ * The response of {@link HttpAdapter.injectStream}: available as soon as the headers are sent, its
+ * body read as it is produced.
+ */
+interface InjectStreamResponse {
+  readonly status: number;
+  /** Like {@link InjectResponse.headers} (`set-cookie` as an array). */
+  readonly headers: Record<string, string | string[]>;
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+  /** The body as it is produced. Cancelling it disconnects the client (the server sees `onAbort` and a cancelled reply body). */
+  readonly body: ReadableStream<Uint8Array>;
+}
+/** Options of {@link HttpAdapter.close}. */
+interface AdapterCloseOptions {
+  /** Destroy open connections instead of waiting for in-flight requests. */
+  readonly force?: boolean;
+}
+/**
+ * A server implementation. Create one with `nodeAdapter()` (default), `fastifyAdapter()`,
+ * `expressAdapter()` or `honoAdapter()`. An adapter instance serves one plugin.
+ */
+interface HttpAdapter {
+  /** `node`, `fastify`, `express`, `hono`... (exposed as `ctx.adapter`). */
+  readonly name: string;
+  /** Registers a route. Called during `onBootstrap`, before `listen`/`inject`. */
+  registerRoute(route: AdapterRoute): void;
+  /** Sets the handler of unmatched requests and framework errors. Called once, before `listen`/`inject`. */
+  setFallbackHandler(handler: FallbackHandler): void;
+  /** Starts listening. `port` 0 picks a free port. */
+  listen(port: number, host: string): Promise<HttpServerAddress>;
+  /**
+   * Stops accepting connections, closes idle ones and resolves once in-flight requests completed and
+   * every connection is closed (`force`: destroys them). Idempotent; also releases what the adapter
+   * created when it never listened.
+   */
+  close(options?: AdapterCloseOptions): Promise<void>;
+  /**
+   * Sends a request in memory (no socket), through the same routing and pipeline, and reads the
+   * whole response. The built-in adapters reject an event stream (`text/event-stream`, which would
+   * never end) with a hint to `injectSse()` / `injectStream()`.
+   */
+  inject(request: InjectRequest): Promise<InjectResponse>;
+  /**
+   * In-memory request whose response body is returned as it is produced (resolves at the headers).
+   * Cancelling `body` (or aborting `signal`) disconnects the client. Optional for third-party
+   * adapters; the four built-in adapters implement it.
+   */
+  injectStream?(request: InjectStreamRequest): Promise<InjectStreamResponse>;
+  /**
+   * WebSocket upgrades (RFC 0003): the adapter routes the upgrade requests `HttpPlugin` asks for
+   * to the pipeline, before its own routing. Optional: an adapter without it cannot serve
+   * `@znight/websocket` gateways. The four built-in adapters implement it.
+   */
+  readonly upgrades?: AdapterUpgrades;
+}
+export { BodyLimit as $, InferSchemaOutput as $n, ContentDispositionType as $t, ExceptionMapperRef as A, ConflictException as An, Validate as At, HstsOptions as B, NotFoundException as Bn, HttpInterceptorClass as Bt, PluginHttpUpgradesContext as C, ByteSize as Cn, RouteMetaEntry as Ct, PluginHttpRoutes as D, parseQuery as Dn, UploadedFiles as Dt, UpgradeHandlerOptions as E, QueryRecord as En, UploadedFile as Et, HttpRouteSummary as F, HttpErrorBody as Fn, ExceptionMapperClass as Ft, ParseSseOptions as G, UnauthorizedException as Gn, isHttpResponse as Gt, TrustProxy as H, PayloadTooLargeException as Hn, HttpResponseInit as Ht, HttpSseOptions as I, HttpException as In, ExceptionMapperResult as It, parseSseStream as J, ValidationException as Jn, SseEvent as Jt, SseItem as K, UnprocessableEntityException as Kn, StreamSource as Kt, InterceptorRef as L, HttpExceptionOptions as Ln, GuardClass as Lt, HttpCookieOptions as M, GatewayTimeoutException as Mn, CallHandler as Mt, HttpPlugin as N, GoneException as Nn, CanActivate as Nt, PluginHttpRoutesContext as O, BadGatewayException as On, UseGuard as Ot, HttpPluginOptions as P, HeaderValue as Pn, ExceptionMapper as Pt, Body as Q, InferSchemaInput as Qn, ByteRange as Qt, TrailingSlashPolicy as R, InternalServerErrorException as Rn, GuardEnforcement as Rt, PluginHttpUpgrades as S, uploads as Sn, RouteMetaCarrier as St, PluginUpgrades as T, parseByteSize as Tn, Sse as Tt, InjectSseResponse as U, ServiceUnavailableException as Un, RedirectStatus as Ut, SecurityHeadersOptions as V, NotImplementedException as Vn, HttpResponse as Vt, InjectSseWaitOptions as W, TooManyRequestsException as Wn, StreamResponseOptions as Wt, CorsOrigin as X, isHttpException as Xn, SseSource as Xt, CorsOptions as Y, ValidationIssueDetail as Yn, SseOptions as Yt, All as Z, toIssueDetail as Zn, encodeSseEvent as Zt, BunUpgrade as _, RequestId as _n, serializeClearCookie as _r, Res as _t, AdapterRoute as a, HttpMetadata as an, StandardSchemaV1Props as ar, Get as at, NodeUpgrade as b, UploadedFilesOptions as bn, RouteDecoratorInfo as bt, HttpServerAddress as c, HttpParamSource as cn, StandardSchemaV1Types as cr, Headers as ct, InjectStreamOptions as d, HttpSseDefinition as dn, CookieDefaults as dr, Param as dt, FileBody as en, StandardSchemaV1 as er, Controller as et, InjectStreamRequest as f, HttpUploadDefinition as fn, CookieOptions as fr, Patch as ft, BunSocketHandlers as g, RequestAbortedError as gn, parseSetCookie as gr, Req as gt, AdapterUpgrades as h, RequestAbortKind as hn, parseCookieHeader as hr, Query as ht, AdapterRequest as i, HttpControllerDefinition as in, StandardSchemaV1PathSegment as ir, Delete as it, GuardRef as j, ForbiddenException as jn, createRouteDecorator as jt, PluginRoute as k, BadRequestException as kn, UseInterceptor as kt, InjectRequest as l, HttpRouteDefinition as ln, isStandardSchema as lr, HttpCode as lt, ReplyBody as m, HttpRouteInfo as mn, SetCookieInfo as mr, Put as mt, AdapterHandler as n, contentDisposition as nn, StandardSchemaV1Issue as nr, Cookie as nt, FallbackHandler as o, HttpMethod as on, StandardSchemaV1Result as or, Head as ot, InjectStreamResponse as p, HttpContext as pn, ResponseCookie as pr, Post as pt, SseMessage as q, UnsupportedMediaTypeException as qn, SseBody as qt, AdapterReply as r, parseRange as rn, StandardSchemaV1Options as rr, Ctx as rt, HttpAdapter as s, HttpParamDefinition as sn, StandardSchemaV1SuccessResult as sr, Header as st, AdapterCloseOptions as t, FileResponseOptions as tn, StandardSchemaV1FailureResult as tr, ControllerOptions as tt, InjectResponse as u, HttpRouteGroupDefinition as un, ClearCookieOptions as ur, Options as ut, MemoryUpgrade as v, UploadLimits as vn, serializeCookie as vr, RouteDecorator as vt, PluginUpgradeRoute as w, formatByteSize as wn, SignedCookie as wt, PendingUpgrade as x, Uploads as xn, RouteDecoratorOptions as xt, NativeUpgrade as y, UploadedFileOptions as yn, RouteDecoratorArgs as yt, EnforcementMode as z, MethodNotAllowedException as zn, HttpInterceptor as zt };
+//# sourceMappingURL=adapter-6qC95ViO.d.mts.map