@znight/http 0.0.0-stage → 0.1.0

package/dist/adapter-CGSceVEN.d.mts

@@ -0,0 +1,876 @@
+import { t as RoutePath } from "./path-JI87C4k8.mjs";
+import { 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>>;
+}
+/**
+ * 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";
+/** 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;
+  /**
+   * Calls the handler: extracts, coerces and validates every argument from the context, then calls
+   * the method on the controller instance. May return a promise.
+   */
+  readonly invoke: (controller: any, ctx: HttpContext) => 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;
+  }
+}
+/** 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 `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>;
+}
+export { PayloadTooLargeException as $, UploadedFileOptions as A, BadRequestException as B, HttpUploadDefinition as C, CookieOptions as Ct, RequestAbortedError as D, parseSetCookie as Dt, RequestAbortKind as E, parseCookieHeader as Et, formatByteSize as F, HeaderValue as G, ForbiddenException as H, parseByteSize as I, HttpExceptionOptions as J, HttpErrorBody as K, QueryRecord as L, Uploads as M, uploads as N, RequestId as O, serializeClearCookie as Ot, ByteSize as P, NotImplementedException as Q, parseQuery as R, HttpSseDefinition as S, CookieDefaults as St, HttpRouteInfo as T, SetCookieInfo as Tt, GatewayTimeoutException as U, ConflictException as V, GoneException as W, MethodNotAllowedException as X, InternalServerErrorException as Y, NotFoundException as Z, HttpMethod as _, StandardSchemaV1Result as _t, AdapterRoute as a, ValidationException as at, HttpRouteDefinition as b, isStandardSchema as bt, HttpServerAddress as c, toIssueDetail as ct, InjectStreamOptions as d, StandardSchemaV1 as dt, ServiceUnavailableException as et, InjectStreamRequest as f, StandardSchemaV1FailureResult as ft, HttpMetadata as g, StandardSchemaV1Props as gt, HttpControllerDefinition as h, StandardSchemaV1PathSegment as ht, AdapterRequest as i, UnsupportedMediaTypeException as it, UploadedFilesOptions as j, UploadLimits as k, serializeCookie as kt, InjectRequest as l, InferSchemaInput as lt, ReplyBody as m, StandardSchemaV1Options as mt, AdapterHandler as n, UnauthorizedException as nt, FallbackHandler as o, ValidationIssueDetail as ot, InjectStreamResponse as p, StandardSchemaV1Issue as pt, HttpException as q, AdapterReply as r, UnprocessableEntityException as rt, HttpAdapter as s, isHttpException as st, AdapterCloseOptions as t, TooManyRequestsException as tt, InjectResponse as u, InferSchemaOutput as ut, HttpParamDefinition as v, StandardSchemaV1SuccessResult as vt, HttpContext as w, ResponseCookie as wt, HttpRouteGroupDefinition as x, ClearCookieOptions as xt, HttpParamSource as y, StandardSchemaV1Types as yt, BadGatewayException as z };
+//# sourceMappingURL=adapter-CGSceVEN.d.mts.map