@znight/http 0.5.1 → 0.6.0

package/dist/index.mjs

@@ -1,15 +1,15 @@
-import { n as RouteTable, t as nodeAdapter } from "./node-DnYv_AMI.mjs";
-import { $ as TooManyRequestsException, A as parseSetCookie, B as BadGatewayException, C as DEFAULT_COOKIE_OPTIONS, D as givenCookieKey, E as encodeCookieValue, F as discardStream, G as GoneException, H as ConflictException, I as isByteStream, J as MethodNotAllowedException, K as HttpException, L as isStreamSource, M as serializeCookie, N as serializeResponseCookie, O as isCookieName, P as captureContext, Q as ServiceUnavailableException, R as toByteStream, T as decodeCookieValue, U as ForbiddenException, V as BadRequestException, W as GatewayTimeoutException, X as NotImplementedException, Y as NotFoundException, Z as PayloadTooLargeException, at as issue, ct as isValidStatus, et as UnauthorizedException, g as isEventStreamType, it as isHttpException, j as serializeClearCookie, k as parseCookieHeader, lt as statusText, nt as UnsupportedMediaTypeException, ot as toIssueDetail, q as InternalServerErrorException, rt as ValidationException, st as isBodylessStatus, tt as UnprocessableEntityException, w as checkCookie, z as trackStream } from "./node-io-BkdRSQeg.mjs";
+import { n as RouteTable, t as nodeAdapter } from "./node-npGnu7IW.mjs";
+import { A as Req, At as ConflictException, B as isGroupOf, Bt as ServiceUnavailableException, C as HttpCode, Ct as discardStream, D as Post, Dt as trackStream, E as Patch, Et as toByteStream, F as UploadedFiles, Ft as InternalServerErrorException, Gt as ValidationException, Ht as UnauthorizedException, I as UseGuard, It as MethodNotAllowedException, Jt as toIssueDetail, Kt as isHttpException, L as UseInterceptor, Lt as NotFoundException, M as SignedCookie, Mt as GatewayTimeoutException, N as Sse, Nt as GoneException, O as Put, Ot as BadGatewayException, P as UploadedFile, Pt as HttpException, R as Validate, Rt as NotImplementedException, S as Headers, St as captureContext, T as Param, Tt as isStreamSource, Ut as UnprocessableEntityException, Vt as TooManyRequestsException, Wt as UnsupportedMediaTypeException, Xt as isValidStatus, Yt as isBodylessStatus, Zt as statusText, _ as Delete, _t as parseCookieHeader, b as Head, bt as serializeCookie, c as checkHandshake, d as All, dt as DEFAULT_COOKIE_OPTIONS, f as Body, ft as checkCookie, g as Ctx, gt as isCookieName, h as Cookie, ht as givenCookieKey, j as Res, jt as ForbiddenException, k as Query, kt as BadRequestException, l as collectPluginUpgrades, m as Controller, mt as encodeCookieValue, n as MemoryUpgradeRequest, nt as injectResponse, o as replyBytes, ot as normalizeInject, p as BodyLimit, pt as decodeCookieValue, qt as issue, rt as isEventStreamType, s as PendingUpgradeState, v as GROUP_NAME, vt as parseSetCookie, w as Options, wt as isByteStream, x as Header, xt as serializeResponseCookie, y as Get, yt as serializeClearCookie, z as createRouteDecorator, zt as PayloadTooLargeException } from "./upgrade-io-dTMDDmBi.mjs";
+import { RoutePathError, compareRoutePaths, compareStrings, decodePathValue, joinPaths, matchRoutePath, normalizePath, parseRoutePath } from "./path.mjs";
 import { a as isMediaTypePattern, i as contentTypeFor, n as parseByteSize, o as matchesMediaType, r as OCTET_STREAM, s as mediaTypeEssence, t as formatByteSize } from "./size-D8rsQcV0.mjs";
 import { a as isThenable, i as isBun, n as errorMessage, r as fastRecord, t as emptyRecord } from "./utils-DIWdzVht.mjs";
-import { RoutePathError, compareRoutePaths, compareStrings, decodePathValue, joinPaths, matchRoutePath, normalizePath, parseRoutePath } from "./path.mjs";
 import { Readable } from "node:stream";
+import { ErrorCode, ZnightError, displayName, resolveOptions } from "@znight/core";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { openAsBlob } from "node:fs";
 import { realpath, stat } from "node:fs/promises";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ErrorCode, ZnightError, displayName, resolveOptions } from "@znight/core";
 import crypto$1, { createHmac, createSecretKey } from "node:crypto";
 // src/multipart.ts
 /** Default maximum size of the headers of one part. */
@@ -1169,252 +1169,6 @@ const EMPTY_HEADERS = Object.freeze({});
 const NO_COOKIES$1 = Object.freeze([]);
 const NO_LINES = Object.freeze([]);
 const NO_FILES$1 = Object.freeze(emptyRecord());
-// src/decorators.ts
-function marker() {}
-const classMarker = marker;
-const methodMarker = marker;
-const parameterMarker = marker;
-const classOrMethodMarker = marker;
-/**
-* 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? }`.
-*/
-function Controller(_pathOrOptions) {
-	return classMarker;
-}
-/** `GET` route. `path` (static) is relative to the controller path; default: the controller path. */
-function Get(_path) {
-	return methodMarker;
-}
-/** `POST` route (default status 201). */
-function Post(_path) {
-	return methodMarker;
-}
-/** `PUT` route. */
-function Put(_path) {
-	return methodMarker;
-}
-/** `PATCH` route. */
-function Patch(_path) {
-	return methodMarker;
-}
-/** `DELETE` route. */
-function Delete(_path) {
-	return methodMarker;
-}
-/** `HEAD` route (`GET` routes already answer `HEAD` requests). */
-function Head(_path) {
-	return methodMarker;
-}
-/** `OPTIONS` route (paths without one answer `OPTIONS` with `204` and an `allow` header). */
-function Options(_path) {
-	return methodMarker;
-}
-/** Route for GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS (methods without a dedicated route on the same path). */
-function All(_path) {
-	return methodMarker;
-}
-function Sse(_pathOrOptions, _options) {
-	return methodMarker;
-}
-function Param(_nameOrSchema, _schema) {
-	return parameterMarker;
-}
-function Query(_nameOrSchema, _schema) {
-	return parameterMarker;
-}
-function Cookie(_nameOrSchema, _schema) {
-	return 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).
-*/
-function SignedCookie(_name, _schema) {
-	return 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...).
-*/
-function Body(_schema) {
-	return 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.
-*/
-function Headers(_name) {
-	return parameterMarker;
-}
-function UploadedFile(_fieldOrOptions, _options) {
-	return parameterMarker;
-}
-function UploadedFiles(_fieldOrOptions, _options) {
-	return 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).
-*/
-function BodyLimit(_size) {
-	return classOrMethodMarker;
-}
-/** Injects the native request of the adapter (escape hatch; the compiler warns). */
-function Req() {
-	return 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.
-*/
-function Res() {
-	return parameterMarker;
-}
-/** Injects the {@link HttpContext} of the request. */
-function Ctx() {
-	return parameterMarker;
-}
-/**
-* Sets the status of successful responses (wins over `HttpResponse.status` and the defaults).
-*
-* @param status static: an integer between 100 and 599.
-*/
-function HttpCode(_status) {
-	return methodMarker;
-}
-/**
-* Adds a header to successful responses. Repeat the decorator for several headers.
-*
-* @param name static: header name.
-* @param value static: header value.
-*/
-function Header(_name, _value) {
-	return 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.
-*/
-function UseGuard(..._guards) {
-	return classOrMethodMarker;
-}
-/**
-* 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.
-*/
-function UseInterceptor(..._interceptors) {
-	return classOrMethodMarker;
-}
-/**
-* Validates the request body with `schema`: sugar for `@Body(schema)` on the body parameter (using
-* both is ZNIGHT005).
-*
-* @param schema value: a Standard Schema.
-*/
-function Validate(_schema) {
-	return methodMarker;
-}
-/**
-* Grammar of an explicit decision group name (internal; the compiler extension has the same rule).
-* A decorator without `group` is its own group, named after its key: any non-empty key is valid.
-*/
-const GROUP_NAME = /^[A-Za-z][\w.-]*$/;
-/** `true` when `group` is a valid group of `key`: the key itself (the default) or a valid name. */
-function isGroupOf(group, key) {
-	return typeof group === "string" && (group === key || GROUP_NAME.test(group));
-}
-/**
-* 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? }`.
-*/
-function createRouteDecorator(key, options) {
-	if (typeof key !== "string" || key === "") throw new TypeError(`createRouteDecorator(): the key must be a non-empty string (received ${String(key)})`);
-	if (options !== void 0 && (options === null || typeof options !== "object")) throw new TypeError(`createRouteDecorator('${key}'): options must be an object { group?, required? }`);
-	const group = options?.group ?? key;
-	if (!isGroupOf(group, key)) throw new TypeError(`createRouteDecorator('${key}'): "group" must be a name made of letters, digits, _ . - starting with a letter (received ${String(group)})`);
-	const required = options?.required ?? false;
-	if (typeof required !== "boolean") throw new TypeError(`createRouteDecorator('${key}'): "required" must be a boolean (received ${String(required)})`);
-	const decorator = (..._args) => classOrMethodMarker;
-	return Object.assign(decorator, {
-		key,
-		group,
-		required,
-		get: (ctx) => ctx.route?.meta[key],
-		meta: (...args) => Object.freeze({
-			key,
-			value: args.length === 0 ? true : args[0],
-			group,
-			required
-		})
-	});
-}
 // src/event-channel.ts
 const DEFAULT_CAPACITY = 1e3;
 /**
@@ -3713,6 +3467,15 @@ const HttpTokens = Object.freeze({
 	Plugin: "@znight/http#HttpPlugin"
 });
 // src/pipeline.ts
+/**
+* The pending upgrade of a handshake context (RFC 0003): set by {@link Pipeline.upgrade} for the
+* upgrade routes only, so that ordinary requests pay nothing.
+*/
+const UPGRADES = /* @__PURE__ */ new WeakMap();
+/** The pending upgrade of the handshake whose context is `ctx` (internal, upgrade routes). */
+function pendingUpgradeOf(ctx) {
+	return UPGRADES.get(ctx);
+}
 /** Default event stream settings. */
 const DEFAULT_SSE_SETTINGS = Object.freeze({
 	heartbeat: 8e3,
@@ -3816,6 +3579,8 @@ var Pipeline = class {
 	#streams = /* @__PURE__ */ new Set();
 	/** Set while the server drains: responses ask clients to close their connection. */
 	draining = false;
+	/** The upgrade routes (RFC 0003), `undefined` when no plugin declares one. */
+	upgrades = void 0;
 	constructor(container, hooks, logger, options, table) {
 		this.#container = container;
 		this.#hooks = hooks;
@@ -4264,6 +4029,71 @@ var Pipeline = class {
 			return Promise.reject(failure);
 		}
 	}
+	/**
+	* Serves a WebSocket handshake (RFC 0003 §8.2.2): the upgrade route of its raw path runs through
+	* the pipeline. Resolves with the reply to write (a refusal), or `undefined` once the transport
+	* took the connection; the request scope then stays open until the connection closes.
+	*/
+	upgrade(request, native) {
+		const startTime = performance.now();
+		try {
+			const url = splitUrl(request.url);
+			const upgrade = this.upgrades?.find("GET", url.path);
+			if (upgrade === void 0) return this.#fallback(request, void 0, startTime);
+			const plan = upgrade.plan;
+			const raw = matchRoutePath(plan.path, url.path) ?? emptyRecord();
+			const params = emptyRecord();
+			let malformed;
+			for (const name of Object.keys(raw)) {
+				const decoded = decodePathValue(raw[name]);
+				if (decoded === void 0) malformed ??= name;
+				else params[name] = decoded;
+			}
+			const target = malformed === void 0 ? {
+				kind: "route",
+				plan
+			} : {
+				kind: "error",
+				error: new BadRequestException(`Malformed URL parameter "${malformed}"`)
+			};
+			let pending;
+			const settled = this.#serve(request, url, plan.info, params, target, startTime, plan.body, (ctx) => {
+				pending = new PendingUpgradeState(native, () => this.#upgradeHeaders(ctx));
+				UPGRADES.set(ctx, pending);
+			}).then((reply) => pending?.accepted === true ? void 0 : reply);
+			const timeoutMs = upgrade.timeoutMs;
+			if (timeoutMs === void 0) return settled;
+			let timer;
+			const expired = new Promise((resolve) => {
+				timer = setTimeout(() => {
+					if (pending !== void 0) pending.expired = true;
+					resolve(adapterReply(serializeError(408, {
+						statusCode: 408,
+						error: "Request Timeout",
+						message: "WebSocket handshake timed out"
+					}, "GET"), null));
+				}, timeoutMs);
+			});
+			return Promise.race([settled, expired]).finally(() => clearTimeout(timer));
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	/** The headers of a `101` response: those set on the context, its cookies and the request id. */
+	#upgradeHeaders(ctx) {
+		const headers = { ...ctx.responseHeaders };
+		const cookies = ctx.cookieLines;
+		if (cookies.length > 0) {
+			const existing = headers["set-cookie"];
+			const raw = [];
+			if (typeof existing === "string") raw.push(existing);
+			else if (existing !== void 0) raw.push(...existing);
+			headers["set-cookie"] = [...raw, ...cookies.map((cookie) => cookie.line)];
+		}
+		const idHeader = this.#options.requestIdHeader;
+		if (idHeader !== void 0 && headers[idHeader] === void 0 && (this.#validIds || isHeaderValue(ctx.requestId))) headers[idHeader] = ctx.requestId;
+		return headers;
+	}
 	#fallback(request, error, startTime, reroute = true) {
 		const body = this.#options.body;
 		if (error !== void 0) {
@@ -4284,7 +4114,7 @@ var Pipeline = class {
 		let target;
 		if (allowed.length === 0) target = {
 			kind: "error",
-			error: new NotFoundException(`Cannot ${request.method} ${truncate(path)}`)
+			error: this.#unmatched(request.method, path)
 		};
 		else if (request.method === "OPTIONS") target = {
 			kind: "options",
@@ -4296,6 +4126,17 @@ var Pipeline = class {
 		};
 		return this.#serve(request, url, void 0, emptyRecord(), target, startTime, body);
 	}
+	/**
+	* The error of a request no route matched: `404`, or `426 Upgrade Required` for a plain `GET` of
+	* a WebSocket gateway path (RFC 0003 §8.2.1).
+	*/
+	#unmatched(method, path) {
+		if ((method === "GET" || method === "HEAD") && this.upgrades?.find("GET", path) !== void 0) return new HttpException(426, "This endpoint only accepts WebSocket connections", void 0, { headers: {
+			upgrade: "websocket",
+			connection: "upgrade"
+		} });
+		return new NotFoundException(`Cannot ${method} ${truncate(path)}`);
+	}
 	/** A CORS preflight (with the `cors` option): answered without running any route. */
 	#isPreflight(request) {
 		return this.#options.cors !== void 0 && isPreflight(request.method, request.headers);
@@ -4309,12 +4150,13 @@ var Pipeline = class {
 		};
 		return this.#serve(request, url, void 0, emptyRecord(), target, startTime, this.#options.body);
 	}
-	#serve(request, url, route, params, target, startTime, body) {
+	#serve(request, url, route, params, target, startTime, body, prepare) {
 		this.#enter();
 		let x;
 		try {
 			const requestId = this.#requestId(request);
 			const ctx = this.#context(request, requestId, url.path, url.query, route, params, body);
+			if (prepare !== void 0) prepare(ctx);
 			if (this.draining && target.kind === "route" && target.plan.definition.sse !== void 0) ctx.abort("shutdown");
 			x = new Exchange(request, ctx, requestId, target, startTime);
 		} catch (error) {
@@ -4384,6 +4226,10 @@ var Pipeline = class {
 		} else if (failed) this.#wrapperFailed(x, hookError);
 		const streaming = this.#send(x, outcome, recheck, run);
 		if (streaming !== void 0) this.#streamed(x, streaming, await streaming.tracked.done);
+		else if (outcome === RAW) {
+			const held = UPGRADES.get(ctx)?.held;
+			if (held !== void 0) await held;
+		}
 	}
 	/**
 	* The reply of a request whose `http:request` wrapper failed before it was handled (`error`), or
@@ -4416,7 +4262,7 @@ var Pipeline = class {
 		const event = x.event;
 		if (outcome === RAW) {
 			ctx.commit();
-			const status = x.request.rawStatus?.() ?? 200;
+			const status = UPGRADES.get(ctx)?.accepted === true ? 101 : x.request.rawStatus?.() ?? 200;
 			event.status ??= status;
 			x.answer({
 				status,
@@ -5762,6 +5608,25 @@ var HttpPlugin = class HttpPlugin {
 	injectSse(request) {
 		return openInjectSse((stream) => this.injectStream(stream), request);
 	}
+	/**
+	* 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`.
+	*/
+	async upgradeInMemory(request, native) {
+		const runtime = this.#require("upgradeInMemory()");
+		const normalized = await normalizeInject(withSignedCookies(request, runtime.options.cookies, "upgradeInMemory()"));
+		const headers = normalized.headers;
+		headers["upgrade"] ??= "websocket";
+		headers["connection"] ??= "Upgrade";
+		headers["sec-websocket-version"] ??= "13";
+		headers["sec-websocket-key"] ??= btoa(String.fromCharCode(...crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16))));
+		headers["host"] ??= "localhost";
+		const reply = await runtime.pipeline.upgrade(new MemoryUpgradeRequest(normalized.method, normalized.url, headers), native);
+		if (reply === void 0) return void 0;
+		return injectResponse(reply.status, reply.headers, await replyBytes(reply));
+	}
 	register(ctx) {
 		if (this.#active) throw new ZnightError(ErrorCode.DuplicateProvider, "This HttpPlugin is already used by another application", { hints: ["Call HttpPlugin.configure() once per application"] });
 		this.#active = true;
@@ -5801,16 +5666,41 @@ var HttpPlugin = class HttpPlugin {
 			cookies: options.cookies,
 			sse: options.sse
 		}, table);
-		const { registrations, checked } = buildRegistrations(ctx, options, raw, collectPluginRoutes(ctx.app.plugins, this, {
-			prefix: options.prefix === "/" ? "" : options.prefix,
+		const prefix = options.prefix === "/" ? "" : options.prefix;
+		const pluginRoutes = collectPluginRoutes(ctx.app.plugins, this, {
+			prefix,
 			container: ctx.container
-		}));
+		});
+		const support = options.adapter.upgrades;
+		const upgrades = collectPluginUpgrades(ctx.app.plugins, this, {
+			prefix,
+			container: ctx.container,
+			adapter: options.adapter.name,
+			upgrades: support?.kind
+		});
+		const { registrations, checked } = buildRegistrations(ctx, options, raw, pluginRoutes, upgrades.routes, pipeline);
 		checkDecisions(checked.routes, checked.groups, options.enforcement, ctx.logger, checked.enforcers);
 		const adapter = options.adapter;
 		const routes = [];
+		let upgradeTable;
 		for (const registration of registrations) {
-			table.add(registration.method, registration.path, registration.plan);
 			const plan = registration.plan;
+			if (registration.upgrade !== void 0) {
+				upgradeTable ??= new RouteTable();
+				upgradeTable.add("GET", registration.path, registration.upgrade);
+				routes.push(Object.freeze({
+					method: "GET",
+					path: registration.path.path,
+					controller: displayName(plan.info.controller),
+					handler: plan.info.handler,
+					source: registration.source,
+					meta: plan.info.meta,
+					guards: registration.guards,
+					upgrade: "websocket"
+				}));
+				continue;
+			}
+			table.add(registration.method, registration.path, registration.plan);
 			adapter.registerRoute({
 				method: registration.method,
 				path: registration.path,
@@ -5827,6 +5717,16 @@ var HttpPlugin = class HttpPlugin {
 			}));
 		}
 		adapter.setFallbackHandler((request, error) => pipeline.fallback(request, error));
+		if (upgradeTable !== void 0) {
+			if (support === void 0) throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, `HttpPlugin: the ${adapter.name} adapter cannot serve WebSocket upgrade routes`, { hints: ["Use a built-in adapter (node, fastify, express, hono) or implement HttpAdapter.upgrades"] });
+			const found = upgradeTable;
+			pipeline.upgrades = found;
+			support.enable({
+				match: (path) => found.find("GET", path) !== void 0,
+				handle: (request, native) => pipeline.upgrade(request, native),
+				bunWebSocket: upgrades.bunWebSocket
+			});
+		}
 		this.#runtime = {
 			adapter,
 			pipeline,
@@ -6068,7 +5968,7 @@ function httpMetadata(metadata) {
 	if (http === null || typeof http !== "object" || !Array.isArray(http.controllers)) throw new ZnightError(ErrorCode.InvalidRoute, "Invalid metadata.extensions.http: expected { controllers: [...] }");
 	return http;
 }
-function buildRegistrations(ctx, options, raw, pluginRoutes) {
+function buildRegistrations(ctx, options, raw, pluginRoutes, upgradeRoutes, pipeline) {
 	const { container, metadata } = ctx;
 	const http = httpMetadata(metadata);
 	const groups = RouteGroups.fromMetadata(http.groups);
@@ -6215,6 +6115,76 @@ function buildRegistrations(ctx, options, raw, pluginRoutes) {
 			meta: () => meta
 		});
 	}
+	for (const route of upgradeRoutes) {
+		const label = `plugin "${route.plugin}" (${route.name})`;
+		const where = `${route.path.path} (${route.name})`;
+		const invalidGuard = (ref) => new ZnightError(ErrorCode.InvalidRoute, `HttpPlugin: plugin "${route.plugin}": the guards of the upgrade route ${where} must be provider tokens, classes or objects with a canActivate() method (received ${describeValue(ref)})`);
+		const guards = [...globalGuards, ...route.guards.map((ref) => typeof ref === "string" ? compiledGuard(ref, `guard of ${where}`) : guardEntries(container, metadata, [ref], invalidGuard)[0])];
+		const values = {};
+		for (const entry of route.meta) {
+			groups.declare(entry, `the plugin "${route.plugin}"`);
+			values[entry.key] = entry.value;
+		}
+		const meta = Object.freeze(values);
+		pending.push(() => checkTargetMeta(meta, groupOf, `the upgrade route ${where} of the plugin "${route.plugin}"`));
+		const accept = route.accept;
+		const precheck = route.precheck;
+		const checks = { canActivate: (ctx) => {
+			checkHandshake(ctx);
+			if (pipeline.draining) throw new ServiceUnavailableException("The server is shutting down", void 0, { headers: { "retry-after": "1" } });
+			if (precheck === void 0) return true;
+			const done = precheck(ctx);
+			return done instanceof Promise ? done.then(() => true) : true;
+		} };
+		const definition = Object.freeze({
+			method: "GET",
+			path: route.relativePath,
+			fullPath: route.relativePath,
+			handler: route.name,
+			meta,
+			guards: [],
+			interceptors: [],
+			params: [],
+			rawResponse: true,
+			invoke: async (_plugin, http) => {
+				const upgrade = pendingUpgradeOf(http);
+				if (upgrade === void 0) throw new Error(`The upgrade route ${where} only serves upgrade requests`);
+				if (upgrade.expired) throw handshakeExpired();
+				await accept(http, upgrade);
+				if (!upgrade.accepted) throw new Error(`accept() of the upgrade route ${where} did not take the connection`);
+			}
+		});
+		const instance = { instance: route.instance };
+		const chain = [{ instance: checks }, ...guards.map((guard) => guard.resolvable)];
+		const body = bodyPlan({}, options.bodyLimit, options.uploads);
+		const path = route.path;
+		declared.push({
+			method: "GET",
+			path,
+			plan: (method) => ({
+				definition,
+				invoke: definition.invoke,
+				path,
+				info: Object.freeze({
+					method,
+					path: path.path,
+					controller: route.owner,
+					handler: route.name,
+					meta
+				}),
+				controller: instance,
+				guards: chain,
+				interceptors: [],
+				parseBody: false,
+				body
+			}),
+			label,
+			source: route.plugin,
+			guards,
+			meta: () => meta,
+			upgrade: { timeoutMs: route.timeoutMs }
+		});
+	}
 	const enforcedGroups = /* @__PURE__ */ new Map();
 	const enforcers = /* @__PURE__ */ new Map();
 	const readEnforces = (cls, name, chained) => {
@@ -6247,17 +6217,31 @@ function buildRegistrations(ctx, options, raw, pluginRoutes) {
 			...route.source === "controller" ? {} : { plugin: route.source }
 		};
 	});
-	const registration = (route, method) => ({
-		method,
-		path: route.path,
-		plan: route.plan(method),
-		label: route.label,
-		source: route.source,
-		guards: Object.freeze(route.guards.map((guard) => guard.name))
-	});
+	const registration = (route, method) => {
+		const plan = route.plan(method);
+		return {
+			method,
+			path: route.path,
+			plan,
+			label: route.label,
+			source: route.source,
+			guards: Object.freeze(route.guards.map((guard) => guard.name)),
+			...route.upgrade === void 0 ? {} : { upgrade: {
+				plan,
+				timeoutMs: route.upgrade.timeoutMs
+			} }
+		};
+	};
 	const explicit = [];
 	const catchAll = [];
-	for (const route of declared) if (route.method === "ALL") catchAll.push(route);
+	const upgradeTable = new RouteTable();
+	const upgrades = [];
+	for (const route of declared) if (route.upgrade !== void 0) {
+		const candidate = registration(route, "GET");
+		const existing = upgradeTable.add("GET", candidate.path, candidate);
+		if (existing !== void 0) throw duplicateRoute(candidate, existing);
+		upgrades.push(candidate);
+	} else if (route.method === "ALL") catchAll.push(route);
 	else explicit.push(registration(route, route.method));
 	const table = new RouteTable();
 	const accepted = [];
@@ -6279,6 +6263,7 @@ function buildRegistrations(ctx, options, raw, pluginRoutes) {
 		catchAllShapes.set(route.path.shape, first);
 		for (const method of CONCRETE_METHODS) add(method === "GET" ? first : registration(route, method), false);
 	}
+	accepted.push(...upgrades);
 	const result = [...accepted];
 	if (options.trailingSlash !== "strict") for (const candidate of accepted) {
 		const path = candidate.path;
@@ -6293,7 +6278,7 @@ function buildRegistrations(ctx, options, raw, pluginRoutes) {
 			wildcard: false,
 			shape: `${path.shape}/`
 		};
-		const plan = options.trailingSlash === "redirect" ? {
+		const plan = options.trailingSlash === "redirect" && candidate.upgrade === void 0 ? {
 			...candidate.plan,
 			path: variant,
 			redirect: true
@@ -6301,10 +6286,15 @@ function buildRegistrations(ctx, options, raw, pluginRoutes) {
 			...candidate.plan,
 			path: variant
 		};
+		const upgrade = candidate.upgrade === void 0 ? {} : { upgrade: {
+			...candidate.upgrade,
+			plan
+		} };
 		result.push({
 			...candidate,
 			path: variant,
-			plan
+			plan,
+			...upgrade
 		});
 	}
 	return {
@@ -6477,6 +6467,10 @@ function resolveRef(container, metadata, ref, what, method, invalid) {
 	}
 	throw invalid();
 }
+/** A handshake completed after its `408`: refused quietly (a 4xx is not logged as a server error). */
+function handshakeExpired() {
+	return new HttpException(408, "WebSocket handshake timed out");
+}
 // src/standard-schema.ts
 /** Whether `value` looks like a Standard Schema v1 (has a `~standard` object with a `validate` function). */
 function isStandardSchema(value) {