@znight/http 0.5.0 → 0.6.0

package/dist/{node-io-BkdRSQeg.mjs → upgrade-io-dTMDDmBi.mjs}

@@ -1,6 +1,8 @@
+import { RoutePathError, joinPaths, normalizePath, parseRoutePath } from "./path.mjs";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { ErrorCode, ZnightError } from "@znight/core";
 // src/status.ts
 /** Standard reason phrases (RFC 9110 and common extensions), used in error bodies. */
 const REASONS = {
@@ -522,7 +524,7 @@ function decodeCookieValue(value) {
 * @throws TypeError for a non-string or a string with lone surrogates (they cannot round-trip).
 */
 function encodeCookieValue(value) {
-	if (typeof value !== "string") throw new TypeError(`A cookie value must be a string (received ${describe(value)})`);
+	if (typeof value !== "string") throw new TypeError(`A cookie value must be a string (received ${describe$1(value)})`);
 	if (!value.isWellFormed()) throw new TypeError("A cookie value must be a well-formed string (it contains a lone surrogate)");
 	let encoded = "";
 	let plain = 0;
@@ -681,8 +683,8 @@ function resolveAttributes(name, options) {
 		partitioned: options.partitioned === true,
 		priority: options.priority
 	};
-	if (attributes.sameSite === "none" && !attributes.secure) throw invalid(name, "SameSite=None requires secure: true (browsers reject it otherwise)");
-	if (attributes.partitioned && !attributes.secure) throw invalid(name, "partitioned cookies require secure: true");
+	if (attributes.sameSite === "none" && !attributes.secure) throw invalid$1(name, "SameSite=None requires secure: true (browsers reject it otherwise)");
+	if (attributes.partitioned && !attributes.secure) throw invalid$1(name, "partitioned cookies require secure: true");
 	checkPrefix(name, attributes);
 	return attributes;
 }
@@ -693,19 +695,19 @@ function checkPrefix(name, attributes) {
 	const http = lower.startsWith("__http-") || lower.startsWith("__host-http-");
 	if (!host && !http && !lower.startsWith("__secure-")) return;
 	const prefix = prefixName(host, http);
-	if (!attributes.secure) throw invalid(name, `the ${prefix} prefix requires secure: true`);
-	if (http && !attributes.httpOnly) throw invalid(name, `the ${prefix} prefix requires httpOnly: true`);
+	if (!attributes.secure) throw invalid$1(name, `the ${prefix} prefix requires secure: true`);
+	if (http && !attributes.httpOnly) throw invalid$1(name, `the ${prefix} prefix requires httpOnly: true`);
 	if (host) {
-		if (attributes.domain !== void 0) throw invalid(name, `the ${prefix} prefix forbids a domain`);
-		if (attributes.path !== "/") throw invalid(name, `the ${prefix} prefix requires path: '/'`);
+		if (attributes.domain !== void 0) throw invalid$1(name, `the ${prefix} prefix forbids a domain`);
+		if (attributes.path !== "/") throw invalid$1(name, `the ${prefix} prefix requires path: '/'`);
 	}
 }
 function checkName(name) {
-	if (!isCookieName(name)) throw new TypeError(`Invalid cookie name ${describe(name)}: expected a token (letters, digits and ! # $ % & ' * + - . ^ _ \` | ~)`);
+	if (!isCookieName(name)) throw new TypeError(`Invalid cookie name ${describe$1(name)}: expected a token (letters, digits and ! # $ % & ' * + - . ^ _ \` | ~)`);
 }
 function encodeValue(name, value) {
-	if (typeof value !== "string") throw invalid(name, `the value must be a string (received ${describe(value)})`);
-	if (!value.isWellFormed()) throw invalid(name, "the value contains a lone surrogate");
+	if (typeof value !== "string") throw invalid$1(name, `the value must be a string (received ${describe$1(value)})`);
+	if (!value.isWellFormed()) throw invalid$1(name, "the value contains a lone surrogate");
 	return encodeCookieValue(value);
 }
 function checkSize(name, wire) {
@@ -716,32 +718,32 @@ function checkSize(name, wire) {
 function checkOptions(name, options, defaults = false) {
 	if (options === void 0) return {};
 	const what = defaults ? "cookies.defaults" : "options";
-	if (options === null || typeof options !== "object" || Array.isArray(options)) throw invalid(name, `${what} must be an object (received ${describe(options)})`);
-	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key)) throw invalid(name, `unknown option "${key}"`);
+	if (options === null || typeof options !== "object" || Array.isArray(options)) throw invalid$1(name, `${what} must be an object (received ${describe$1(options)})`);
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key)) throw invalid$1(name, `unknown option "${key}"`);
 	const { maxAge, expires, domain, path, secure, httpOnly, sameSite, partitioned, priority, signed } = options;
-	if (maxAge !== void 0 && !(typeof maxAge === "number" && Number.isSafeInteger(maxAge))) throw invalid(name, `maxAge must be an integer number of seconds (received ${describe(maxAge)})`);
-	if (expires !== void 0 && !(expires instanceof Date && !Number.isNaN(expires.getTime()))) throw invalid(name, `expires must be a valid Date (received ${describe(expires)})`);
+	if (maxAge !== void 0 && !(typeof maxAge === "number" && Number.isSafeInteger(maxAge))) throw invalid$1(name, `maxAge must be an integer number of seconds (received ${describe$1(maxAge)})`);
+	if (expires !== void 0 && !(expires instanceof Date && !Number.isNaN(expires.getTime()))) throw invalid$1(name, `expires must be a valid Date (received ${describe$1(expires)})`);
 	if (expires !== void 0) {
 		const year = expires.getUTCFullYear();
-		if (year < MIN_EXPIRES_YEAR || year > MAX_EXPIRES_YEAR) throw invalid(name, `expires must be in the years ${MIN_EXPIRES_YEAR} to ${MAX_EXPIRES_YEAR} (received ${expires.toISOString()}): browsers ignore other dates; use maxAge for a long lifetime (browsers cap it at 400 days)`);
+		if (year < MIN_EXPIRES_YEAR || year > MAX_EXPIRES_YEAR) throw invalid$1(name, `expires must be in the years ${MIN_EXPIRES_YEAR} to ${MAX_EXPIRES_YEAR} (received ${expires.toISOString()}): browsers ignore other dates; use maxAge for a long lifetime (browsers cap it at 400 days)`);
 	}
-	if (domain !== void 0 && domain !== null && typeof domain !== "string") throw invalid(name, `domain must be a string or null (received ${describe(domain)})`);
-	if (path !== void 0 && typeof path !== "string") throw invalid(name, `path must be a string (received ${describe(path)})`);
+	if (domain !== void 0 && domain !== null && typeof domain !== "string") throw invalid$1(name, `domain must be a string or null (received ${describe$1(domain)})`);
+	if (path !== void 0 && typeof path !== "string") throw invalid$1(name, `path must be a string (received ${describe$1(path)})`);
 	for (const [key, flag] of [
 		["secure", secure],
 		["httpOnly", httpOnly],
 		["partitioned", partitioned],
 		["signed", signed]
-	]) if (flag !== void 0 && typeof flag !== "boolean") throw invalid(name, `${key} must be a boolean (received ${describe(flag)})`);
-	if (sameSite !== void 0 && !Object.hasOwn(SAME_SITE, sameSite)) throw invalid(name, `sameSite must be 'strict', 'lax' or 'none' (received ${describe(sameSite)})`);
-	if (priority !== void 0 && !Object.hasOwn(PRIORITY, priority)) throw invalid(name, `priority must be 'low', 'medium' or 'high' (received ${describe(priority)})`);
+	]) if (flag !== void 0 && typeof flag !== "boolean") throw invalid$1(name, `${key} must be a boolean (received ${describe$1(flag)})`);
+	if (sameSite !== void 0 && !Object.hasOwn(SAME_SITE, sameSite)) throw invalid$1(name, `sameSite must be 'strict', 'lax' or 'none' (received ${describe$1(sameSite)})`);
+	if (priority !== void 0 && !Object.hasOwn(PRIORITY, priority)) throw invalid$1(name, `priority must be 'low', 'medium' or 'high' (received ${describe$1(priority)})`);
 	return options;
 }
 /** Lower-cased, one leading `.` removed; an ASCII host name of at most 253 characters. */
 function normalizeDomain(name, domain) {
 	const normalized = (domain.startsWith(".") ? domain.slice(1) : domain).toLowerCase();
 	if (normalized.length > 1024) throw new RangeError(`Invalid cookie "${name}": the domain exceeds ${MAX_COOKIE_ATTRIBUTE_SIZE} bytes`);
-	if (!isHostName(normalized)) throw invalid(name, `invalid domain ${describe(domain)}: expected an ASCII host name (letters, digits, -, dot-separated labels; IDNs in punycode)`);
+	if (!isHostName(normalized)) throw invalid$1(name, `invalid domain ${describe$1(domain)}: expected an ASCII host name (letters, digits, -, dot-separated labels; IDNs in punycode)`);
 	return normalized;
 }
 function isHostName(domain) {
@@ -767,7 +769,7 @@ function checkPath(name, path) {
 		const code = path.charCodeAt(index);
 		valid = code >= 32 && code <= 126 && code !== 59;
 	}
-	if (!valid) throw invalid(name, `invalid path ${describe(path)}: expected "/..." made of visible ASCII characters without ";"`);
+	if (!valid) throw invalid$1(name, `invalid path ${describe$1(path)}: expected "/..." made of visible ASCII characters without ";"`);
 }
 /** The options without `undefined` values (they would erase defaults when spread). */
 function definedOnly(options) {
@@ -789,7 +791,7 @@ function parseSetCookie(line) {
 	const pair = parts[0];
 	const equals = pair.indexOf("=");
 	const name = equals === -1 ? "" : trim(pair, 0, equals);
-	if (name === "") throw new TypeError(`Invalid Set-Cookie line ${describe(line)}: missing name=value`);
+	if (name === "") throw new TypeError(`Invalid Set-Cookie line ${describe$1(line)}: missing name=value`);
 	const info = {
 		name,
 		value: decodeCookieValue(unquote(trim(pair, equals + 1, pair.length))),
@@ -868,7 +870,7 @@ function prefixName(host, http) {
 	if (host) return http ? "__Host-Http-" : "__Host-";
 	return http ? "__Http-" : "__Secure-";
 }
-function invalid(name, reason) {
+function invalid$1(name, reason) {
 	return /* @__PURE__ */ new TypeError(`Invalid cookie "${name}": ${reason}`);
 }
 function byteLength(text) {
@@ -881,7 +883,7 @@ function byteLength(text) {
 	}
 	return size;
 }
-function describe(value) {
+function describe$1(value) {
 	if (typeof value === "string") return JSON.stringify(value.length > 64 ? `${value.slice(0, 64)}…` : value);
 	if (value instanceof Date) return "an invalid Date";
 	if (value === null) return "null";
@@ -976,6 +978,19 @@ function injectHeaders(headers) {
 	}
 	return normalized;
 }
+/** Builds an {@link InjectResponse} (headers normalised by {@link injectHeaders}, cookies parsed). */
+function injectResponse(status, headers, bytes) {
+	const normalized = injectHeaders(headers);
+	const body = DECODER.decode(bytes);
+	return {
+		status,
+		headers: normalized,
+		body,
+		bytes,
+		cookies: parseSetCookies(normalized["set-cookie"]),
+		json: () => JSON.parse(body)
+	};
+}
 /** Whether a `content-type` is `text/event-stream`. */
 function isEventStreamType(contentType) {
 	if (typeof contentType !== "string") return false;
@@ -1609,6 +1624,13 @@ var ConnectionTracker = class ConnectionTracker {
 		for (const socket of this.#sockets) socket.destroy();
 	}
 };
+/**
+* Marks a socket taken over by a WebSocket transport (RFC 0003) as busy: a graceful close of the
+* server leaves it to its transport, which closes it with a close frame; a forced close destroys it.
+*/
+function markUpgraded(socket) {
+	socket[ACTIVE] = 1;
+}
 /** Closes a `node:http` server: graceful (idle connections ended), then forced when asked. */
 function closeServer(server, tracker, closing, force) {
 	const promise = closing ?? new Promise((resolve) => {
@@ -1626,6 +1648,582 @@ function closeServer(server, tracker, closing, force) {
 	}
 	return promise;
 }
-export { TooManyRequestsException as $, parseSetCookie as A, BadGatewayException as B, DEFAULT_COOKIE_OPTIONS as C, givenCookieKey as D, encodeCookieValue as E, discardStream as F, GoneException as G, ConflictException as H, isByteStream as I, MethodNotAllowedException as J, HttpException as K, isStreamSource as L, serializeCookie as M, serializeResponseCookie as N, isCookieName as O, captureContext as P, ServiceUnavailableException as Q, toByteStream as R, webBodyStream as S, decodeCookieValue as T, ForbiddenException as U, BadRequestException as V, GatewayTimeoutException as W, NotImplementedException as X, NotFoundException as Y, PayloadTooLargeException as Z, lightInjectOptions as _, nodeBodyStream as a, issue as at, readWebStream as b, readNodeBody as c, isValidStatus as ct, writeNodeReply as d, UnauthorizedException as et, bufferInjectStream as f, isEventStreamType as g, injectNodeStream as h, nodeAdapterRequest as i, isHttpException as it, serializeClearCookie as j, parseCookieHeader as k, withNativeCookies as l, statusText as lt, injectFetchStream as m, closeServer as n, UnsupportedMediaTypeException as nt, normalizeNodeHeaders as o, toIssueDetail as ot, exceedsDeclaredLength as p, InternalServerErrorException as q, isEncrypted as r, ValidationException as rt, onResponseAbort as s, isBodylessStatus as st, ConnectionTracker as t, UnprocessableEntityException as tt, writeNodeFailure as u, lightStreamResponse as v, checkCookie as w, serverAddress as x, payloadTooLarge as y, trackStream as z };
+// 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$1(_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/upgrade.ts
+/** Calls `httpUpgrades()` on every other plugin implementing it, in plugin order, and validates the routes. */
+function collectPluginUpgrades(plugins, self, context) {
+	const routes = [];
+	const bunWebSocket = {};
+	for (const plugin of plugins) {
+		if (plugin === self) continue;
+		const provider = plugin;
+		if (typeof provider.httpUpgrades !== "function") continue;
+		const name = String(provider.name);
+		const result = provider.httpUpgrades(context);
+		const declared = result?.routes;
+		if (!Array.isArray(declared)) throw invalid(name, `httpUpgrades() must return { routes: [...] } (received ${describe(result)})`);
+		for (const route of declared) routes.push(validateRoute(plugin, name, route, context.prefix));
+		const settings = result.bunWebSocket;
+		if (settings !== void 0) Object.assign(bunWebSocket, settings);
+	}
+	return {
+		routes,
+		bunWebSocket
+	};
+}
+function validateRoute(instance, plugin, value, prefix) {
+	if (value === null || typeof value !== "object") throw invalid(plugin, `invalid upgrade route ${describe(value)}`);
+	const route = value;
+	if (typeof route.name !== "string" || route.name === "") throw invalid(plugin, `the upgrade route ${String(route.path)} needs a name`);
+	const where = `${String(route.path)} (${route.name})`;
+	if (typeof route.path !== "string") throw invalid(plugin, `the upgrade route ${where} has no path`);
+	if (typeof route.accept !== "function") throw invalid(plugin, `the upgrade route ${where} has no accept function`);
+	if (route.precheck !== void 0 && typeof route.precheck !== "function") throw invalid(plugin, `the precheck of the upgrade route ${where} must be a function`);
+	let path;
+	try {
+		path = parseRoutePath(joinPaths(prefix, route.path));
+	} catch (error) {
+		if (!(error instanceof RoutePathError)) throw error;
+		throw invalid(plugin, `invalid path of the upgrade route ${where}: ${error.issue.message}`, error);
+	}
+	const meta = route.meta ?? [];
+	if (!Array.isArray(meta)) throw invalid(plugin, `the meta of the upgrade route ${where} must be an array of entries`);
+	const entries = meta.map((entry) => metaEntry(plugin, where, entry));
+	const guards = route.guards ?? [];
+	if (!Array.isArray(guards)) throw invalid(plugin, `the guards of the upgrade route ${where} must be an array`);
+	const timeoutMs = route.timeoutMs;
+	if (timeoutMs !== void 0 && !(typeof timeoutMs === "number" && timeoutMs > 0)) throw invalid(plugin, `invalid timeoutMs ${describe(timeoutMs)} of the upgrade route ${where}`);
+	return {
+		plugin,
+		instance,
+		path,
+		relativePath: normalizePath(route.path),
+		name: route.name,
+		owner: route.owner ?? plugin,
+		meta: entries,
+		guards,
+		timeoutMs: timeoutMs === Number.POSITIVE_INFINITY ? void 0 : timeoutMs,
+		precheck: route.precheck?.bind(route),
+		accept: route.accept.bind(route)
+	};
+}
+function metaEntry(plugin, where, value) {
+	const entry = value ?? {};
+	if (value === null || typeof value !== "object" || typeof entry.key !== "string" || entry.key === "") throw invalid(plugin, `invalid meta entry ${describe(value)} of the upgrade route ${where}`);
+	const group = entry.group ?? entry.key;
+	const required = entry.required ?? false;
+	if (!isGroupOf(group, entry.key) || typeof required !== "boolean") throw invalid(plugin, `invalid group of the meta entry "${entry.key}" of the upgrade route ${where}`);
+	return {
+		key: entry.key,
+		value: entry.value,
+		group,
+		required
+	};
+}
+function invalid(plugin, reason, cause) {
+	return new ZnightError(ErrorCode.InvalidRoute, `HttpPlugin: plugin "${plugin}": ${reason}`, { ...cause === void 0 ? {} : { cause } });
+}
+function describe(value) {
+	try {
+		return typeof value === "function" ? "a function" : JSON.stringify(value) ?? String(value);
+	} catch {
+		return typeof value;
+	}
+}
+const KEY = /^[A-Za-z0-9+/]{22}==$/;
+/** Whether a request asks for a WebSocket upgrade (`upgrade: websocket`, any case). */
+function isWebSocketUpgrade(headers) {
+	const upgrade = headers["upgrade"];
+	return upgrade !== void 0 && upgrade.length === 9 && upgrade.toLowerCase() === "websocket";
+}
+/**
+* The protocol checks of a handshake: `GET`, `sec-websocket-version: 13` (`426` with the supported
+* version otherwise) and a base64 16-byte `sec-websocket-key` (`400`).
+*/
+function checkHandshake(ctx) {
+	if (ctx.method !== "GET") throw new BadRequestException("A WebSocket handshake must be a GET request");
+	if (ctx.headers["sec-websocket-version"] !== "13") throw new HttpException(426, "Unsupported WebSocket version", void 0, { headers: { "sec-websocket-version": "13" } });
+	const key = ctx.headers["sec-websocket-key"];
+	if (key === void 0 || !KEY.test(key.trim())) throw new BadRequestException("Invalid Sec-WebSocket-Key");
+}
+/** Internal: the pending upgrade of a handshake, created by the pipeline. */
+var PendingUpgradeState = class {
+	native;
+	#headers;
+	/** The transport completed the handshake (`101`). */
+	accepted = false;
+	/** The handshake timed out: the transport must not complete it. */
+	expired = false;
+	held;
+	constructor(native, headers) {
+		this.native = native;
+		this.#headers = headers;
+	}
+	get headers() {
+		return this.#headers();
+	}
+	hold(closed) {
+		if (this.held !== void 0) throw new Error("PendingUpgrade.hold() can only be called once");
+		this.accepted = true;
+		this.held = closed.then(() => void 0, () => void 0);
+	}
+};
+// src/adapters/upgrade-io.ts
+const EMPTY = /* @__PURE__ */ new Uint8Array(0);
+/** A handshake has no body: Znight never reads one. */
+const NO_BODY = Promise.resolve(EMPTY);
+/** The `IncomingMessage` of a `node:http` upgrade as an {@link AdapterRequest}. */
+var NodeUpgradeRequest = class {
+	method;
+	url;
+	headers;
+	ip;
+	remoteAddress;
+	encrypted;
+	raw;
+	rawResponse;
+	constructor(request, socket) {
+		const peer = socket.remoteAddress ?? request.socket?.remoteAddress;
+		this.method = request.method ?? "GET";
+		this.url = request.url ?? "/";
+		this.headers = normalizeNodeHeaders(request.headers);
+		this.ip = peer;
+		this.remoteAddress = peer;
+		this.encrypted = request.socket?.encrypted === true;
+		this.raw = request;
+		this.rawResponse = socket;
+	}
+	readBody() {
+		return NO_BODY;
+	}
+	hasBody() {
+		return false;
+	}
+};
+/** The Fetch `Request` of a `Bun.serve()` upgrade as an {@link AdapterRequest}. */
+var FetchUpgradeRequest = class {
+	method;
+	url;
+	headers;
+	ip;
+	remoteAddress;
+	encrypted;
+	raw;
+	rawResponse = void 0;
+	constructor(request, url, headers, address) {
+		this.method = request.method;
+		this.url = url;
+		this.headers = headers;
+		this.ip = address;
+		this.remoteAddress = address;
+		this.encrypted = request.url.startsWith("https:");
+		this.raw = request;
+	}
+	readBody() {
+		return NO_BODY;
+	}
+	hasBody() {
+		return false;
+	}
+};
+/** An in-memory handshake (`HttpPlugin.upgradeInMemory()`) as an {@link AdapterRequest}. */
+var MemoryUpgradeRequest = class {
+	method;
+	url;
+	headers;
+	ip = "127.0.0.1";
+	remoteAddress = "127.0.0.1";
+	encrypted = false;
+	raw = void 0;
+	rawResponse = void 0;
+	constructor(method, url, headers) {
+		this.method = method;
+		this.url = url;
+		this.headers = headers;
+	}
+	readBody() {
+		return NO_BODY;
+	}
+	hasBody() {
+		return false;
+	}
+};
+/** The bytes of a reply body (refusals are small: read whole). */
+async function replyBytes(reply) {
+	const body = reply.body;
+	if (body === null) return EMPTY;
+	if (body instanceof Uint8Array) return body;
+	if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer());
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of body) {
+		chunks.push(chunk);
+		size += chunk.byteLength;
+	}
+	return concat(chunks, size);
+}
+/** Whether a header value can be written on a raw socket (no CR/LF injection). */
+function safeHeader(value) {
+	return !/[\r\n]/.test(value);
+}
+/**
+* Writes a refused handshake as a raw HTTP/1.1 response on the upgrade socket, then ends it
+* (`connection: close`). Never throws.
+*/
+async function writeRawRefusal(socket, reply) {
+	try {
+		const body = await replyBytes(reply);
+		let head = `HTTP/1.1 ${reply.status} ${statusText(reply.status)}\r\n`;
+		const headers = { ...reply.headers };
+		headers["connection"] = "close";
+		headers["content-length"] = String(body.byteLength);
+		for (const [name, value] of Object.entries(headers)) for (const item of typeof value === "string" ? [value] : value) if (safeHeader(name) && safeHeader(item)) head += `${name}: ${item}\r\n`;
+		head += "\r\n";
+		if (socket.destroyed) return;
+		socket.write(head);
+		if (body.byteLength > 0) socket.write(body);
+		socket.end();
+		setTimeout(() => socket.destroy(), 1e3).unref?.();
+	} catch {
+		socket.destroy();
+	}
+}
+/** The fallback reply when the pipeline failed (never expected). */
+const FAILURE = Object.freeze({
+	status: 500,
+	headers: {},
+	body: null
+});
+/**
+* The upgrade capability of an adapter built on a `node:http` server (RFC 0003 §8.2.3): upgrade
+* requests of the gateway paths are routed to the pipeline through `shouldUpgradeCallback`
+* (composed with the server's own) and an `'upgrade'` listener; other upgrade requests are left to
+* the server (its own listeners, or ordinary requests).
+*/
+var NodeUpgrades = class {
+	kind = "node";
+	#options;
+	#attached = /* @__PURE__ */ new WeakSet();
+	/** Whether {@link enable} was called. */
+	get enabled() {
+		return this.#options !== void 0;
+	}
+	enable(options) {
+		this.#options = options;
+	}
+	/** Routes the gateway upgrades of `server` to the pipeline (once per server; no-op when not enabled). */
+	attach(server) {
+		const options = this.#options;
+		if (options === void 0 || this.#attached.has(server)) return;
+		this.#attached.add(server);
+		const matches = (request) => {
+			if (!isWebSocketUpgrade(request.headers)) return false;
+			const url = request.url ?? "/";
+			const query = url.indexOf("?");
+			return options.match(query === -1 ? url : url.slice(0, query));
+		};
+		const target = server;
+		const previous = target.shouldUpgradeCallback;
+		const composable = typeof previous === "function";
+		const listener = (request, socket, head) => {
+			if (!matches(request)) {
+				if (!composable && server.listenerCount("upgrade") === 1) writeRawRefusal(socket, {
+					status: 404,
+					headers: {},
+					body: null
+				});
+				return;
+			}
+			socket.on("error", () => socket.destroy());
+			markUpgraded(socket);
+			const native = {
+				kind: "node",
+				request,
+				socket,
+				head
+			};
+			options.handle(new NodeUpgradeRequest(request, socket), native).then((reply) => {
+				if (reply !== void 0) writeRawRefusal(socket, reply);
+			}, () => void writeRawRefusal(socket, FAILURE));
+		};
+		if (previous !== void 0) target.shouldUpgradeCallback = function(request) {
+			if (matches(request)) return true;
+			const self = this ?? server;
+			const view = Object.create(self, { listenerCount: { value: (name) => self.listenerCount(name) - (name === "upgrade" ? 1 : 0) } });
+			return previous.call(view, request) === true;
+		};
+		server.on("upgrade", listener);
+	}
+};
+/**
+* The `websocket` option of `Bun.serve()`: the plugins' settings, and handlers dispatching every
+* event to the {@link BunSocketHandlers} given as `data` to `server.upgrade()`.
+*/
+function bunWebSocketOption(settings) {
+	return Object.freeze({
+		...settings,
+		open: (ws) => ws.data.open(ws),
+		message: (ws, message) => ws.data.message(ws, message),
+		close: (ws, code, reason) => ws.data.close(ws, code, reason),
+		drain: (ws) => ws.data.drain(ws),
+		pong: (ws) => ws.data.pong?.(ws)
+	});
+}
+/** Builds the `Response` of a refused `Bun.serve()` upgrade. */
+async function refusalResponse(reply) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(reply.headers)) for (const item of typeof value === "string" ? [value] : value) headers.append(name, item);
+	const body = await replyBytes(reply);
+	return new Response(body.byteLength === 0 ? null : body, {
+		status: reply.status,
+		headers
+	});
+}
+export { exceedsDeclaredLength as $, Req as A, ConflictException as At, isGroupOf as B, ServiceUnavailableException as Bt, HttpCode as C, discardStream as Ct, Post as D, trackStream as Dt, Patch as E, toByteStream as Et, UploadedFiles as F, InternalServerErrorException as Ft, nodeBodyStream as G, ValidationException as Gt, closeServer as H, UnauthorizedException as Ht, UseGuard as I, MethodNotAllowedException as It, readNodeBody as J, toIssueDetail as Jt, normalizeNodeHeaders as K, isHttpException as Kt, UseInterceptor as L, NotFoundException as Lt, SignedCookie as M, GatewayTimeoutException as Mt, Sse as N, GoneException as Nt, Put as O, BadGatewayException as Ot, UploadedFile as P, HttpException as Pt, bufferInjectStream as Q, Validate as R, NotImplementedException as Rt, Headers$1 as S, captureContext as St, Param as T, isStreamSource as Tt, isEncrypted as U, UnprocessableEntityException as Ut, ConnectionTracker as V, TooManyRequestsException as Vt, nodeAdapterRequest as W, UnsupportedMediaTypeException as Wt, writeNodeFailure as X, isValidStatus as Xt, withNativeCookies as Y, isBodylessStatus as Yt, writeNodeReply as Z, statusText as Zt, Delete as _, parseCookieHeader as _t, refusalResponse as a, lightStreamResponse as at, Head as b, serializeCookie as bt, checkHandshake as c, readWebStream as ct, All as d, DEFAULT_COOKIE_OPTIONS as dt, injectFetchStream as et, Body as f, checkCookie as ft, Ctx as g, isCookieName as gt, Cookie as h, givenCookieKey as ht, bunWebSocketOption as i, lightInjectOptions as it, Res as j, ForbiddenException as jt, Query as k, BadRequestException as kt, collectPluginUpgrades as l, serverAddress as lt, Controller as m, encodeCookieValue as mt, MemoryUpgradeRequest as n, injectResponse as nt, replyBytes as o, normalizeInject as ot, BodyLimit as p, decodeCookieValue as pt, onResponseAbort as q, issue as qt, NodeUpgrades as r, isEventStreamType as rt, PendingUpgradeState as s, payloadTooLarge as st, FetchUpgradeRequest as t, injectNodeStream as tt, isWebSocketUpgrade as u, webBodyStream as ut, GROUP_NAME as v, parseSetCookie as vt, Options as w, isByteStream as wt, Header as x, serializeResponseCookie as xt, Get as y, serializeClearCookie as yt, createRouteDecorator as z, PayloadTooLargeException as zt };
 
-//# sourceMappingURL=node-io-BkdRSQeg.mjs.map
+//# sourceMappingURL=upgrade-io-dTMDDmBi.mjs.map