@askrjs/node 0.0.8 → 0.0.11

package/dist/index.js

@@ -1,41 +1,150 @@
-import { Readable } from "node:stream";
+import { isIP } from "node:net";
+import { addAbortListener } from "node:events";
 import { createServer } from "node:http";
-import { WebSocketServer } from "ws";
+import { WebSocket, WebSocketServer } from "ws";
 import { createReadStream } from "node:fs";
 import { realpath, stat } from "node:fs/promises";
 import { extname, resolve, sep } from "node:path";
+import { pipeline } from "node:stream";
+//#region src/client-address.ts
+/**
+* Reserved request header containing the TCP peer address authenticated by the Node adapter.
+* Any value supplied by the HTTP client is overwritten before application dispatch.
+*/
+const CLIENT_ADDRESS_HEADER = "x-askr-client-address";
+/** Normalizes the socket peer address used for the adapter-authenticated request header. */
+function normalizeClientAddress(address) {
+	if (!address) return "unknown";
+	if (address.toLowerCase().startsWith("::ffff:")) {
+		const mapped = address.slice(7);
+		if (isIP(mapped) === 4) return mapped;
+	}
+	return address;
+}
+//#endregion
 //#region src/request.ts
 var NodeRequestError = class extends TypeError {};
+function explicitPort(authority) {
+	if (authority.startsWith("[")) {
+		const bracket = authority.indexOf("]");
+		return bracket >= 0 && authority[bracket + 1] === ":" ? authority.slice(bracket + 2) : void 0;
+	}
+	const first = authority.indexOf(":");
+	return first >= 0 && first === authority.lastIndexOf(":") ? authority.slice(first + 1) : void 0;
+}
+function parseAuthority(value, allowBareIpv6 = false) {
+	if (!value || value.trim() !== value) throw new NodeRequestError("Request host must be a non-empty HTTP authority.");
+	const bareIpv6 = isIP(value) === 6;
+	if (bareIpv6 && !allowBareIpv6) throw new NodeRequestError("IPv6 request hosts must use brackets.");
+	const authority = bareIpv6 ? `[${value}]` : value;
+	const port = explicitPort(authority);
+	let parsed;
+	try {
+		parsed = new URL(`http://${authority}`);
+	} catch {
+		throw new NodeRequestError("Request host is not a valid HTTP authority.");
+	}
+	if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash || port !== void 0 && !/^\d+$/u.test(port)) throw new NodeRequestError("Request host is not a valid HTTP authority.");
+	return {
+		hostname: parsed.hostname,
+		host: port === void 0 ? parsed.hostname : `${parsed.hostname}:${Number(port)}`
+	};
+}
+function prepareBaseUrl(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new TypeError("Node handler baseUrl must be a valid HTTP or HTTPS origin.");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) throw new TypeError("Node handler baseUrl must be an HTTP or HTTPS origin.");
+	return parsed.origin;
+}
+function prepareNodeHandlerOptions(options) {
+	const allowedHosts = (options.allowedHosts ?? []).map((value) => {
+		try {
+			const parsed = parseAuthority(value, true);
+			return explicitPort(isIP(value) === 6 ? `[${value}]` : value) === void 0 ? { hostname: parsed.hostname } : parsed;
+		} catch (error) {
+			throw new TypeError(`Node handler allowedHosts contains an invalid host: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+	const baseUrl = options.baseUrl === void 0 ? void 0 : prepareBaseUrl(options.baseUrl);
+	if (!baseUrl && allowedHosts.length === 0) throw new TypeError("Node handling requires baseUrl or an allowedHosts allowlist.");
+	return {
+		allowedHosts,
+		baseUrl,
+		hostCache: {}
+	};
+}
 function requestHeaders(request) {
 	const headers = new Headers();
-	for (const [key, value] of Object.entries(request.headers)) {
+	for (const key in request.headers) {
+		const value = request.headers[key];
 		if (value === void 0) continue;
-		headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+		if (Array.isArray(value)) for (const item of value) headers.append(key, item);
+		else headers.set(key, value);
 	}
+	headers.set(CLIENT_ADDRESS_HEADER, normalizeClientAddress(request.socket.remoteAddress));
 	return headers;
 }
-function resolveNodeRequestUrl(request, options) {
+function resolveNodeRequestHref(request, options) {
 	const host = request.headers.host;
-	if (!options.baseUrl && !options.allowedHosts?.length) throw new NodeRequestError("Node handling requires baseUrl or an allowedHosts allowlist.");
 	if (!host) throw new NodeRequestError("Request Host header is required.");
-	const hostName = host.startsWith("[") ? host.slice(1, host.indexOf("]")) : host.split(":", 1)[0];
-	if (options.allowedHosts?.length && !options.allowedHosts.some((allowed) => allowed === host || allowed === hostName)) throw new NodeRequestError("Request Host header is not allowed.");
-	const base = options.baseUrl ?? `http://${host}`;
-	const target = new URL(request.url ?? "/", base);
-	if (/^https?:\/\//i.test(request.url ?? "") && target.origin !== new URL(base).origin) throw new NodeRequestError("Absolute-form request target origin is not allowed.");
-	return target;
+	let base = options.hostCache.value === host ? options.hostCache.base : void 0;
+	if (!base) {
+		const authority = parseAuthority(host);
+		if (options.allowedHosts.length > 0 && !options.allowedHosts.some((allowed) => allowed.host === void 0 ? allowed.hostname === authority.hostname : allowed.host === authority.host)) throw new NodeRequestError("Request Host header is not allowed.");
+		base = options.baseUrl ?? `http://${authority.host}`;
+		options.hostCache.value = host;
+		options.hostCache.base = base;
+	}
+	const requestTarget = request.url || "/";
+	if (requestTarget === "*") {
+		if (request.method === "OPTIONS") return `${base}/*`;
+		throw new NodeRequestError("Asterisk-form request targets require OPTIONS.");
+	}
+	if (requestTarget.startsWith("//")) throw new NodeRequestError("Network-path request targets are not allowed.");
+	if (requestTarget.startsWith("/")) {
+		if (requestTarget.includes("\\")) throw new NodeRequestError("Request targets must not contain backslashes.");
+		if (requestTarget.includes("#")) throw new NodeRequestError("Request targets must not contain fragments.");
+		return `${base}${requestTarget}`;
+	}
+	if (!/^https?:\/\//iu.test(requestTarget)) throw new NodeRequestError("Request target must use origin-form or absolute-form.");
+	let target;
+	try {
+		target = new URL(requestTarget, base);
+	} catch {
+		throw new NodeRequestError("Request target is not a valid HTTP URL.");
+	}
+	if (target.origin !== new URL(base).origin) throw new NodeRequestError("Absolute-form request target origin is not allowed.");
+	if (target.hash) throw new NodeRequestError("Request targets must not contain fragments.");
+	return target.href;
+}
+function resolveNodeRequestUrl(request, options) {
+	try {
+		return new URL(resolveNodeRequestHref(request, options));
+	} catch (error) {
+		if (error instanceof NodeRequestError) throw error;
+		throw new NodeRequestError("Request target is not a valid HTTP URL.");
+	}
 }
 function requestFromNode(request, options, signal) {
-	const target = resolveNodeRequestUrl(request, options);
+	const target = resolveNodeRequestHref(request, options);
 	const method = request.method ?? "GET";
-	const body = method === "GET" || method === "HEAD" ? void 0 : Readable.toWeb(request);
-	return new Request(target, {
-		method,
-		headers: requestHeaders(request),
-		body,
-		signal,
-		...body ? { duplex: "half" } : {}
-	});
+	if (method === "GET" || method === "HEAD") request.resume();
+	const body = method === "GET" || method === "HEAD" ? void 0 : request;
+	try {
+		return new Request(target, {
+			method,
+			headers: requestHeaders(request),
+			body,
+			signal,
+			...body ? { duplex: "half" } : {}
+		});
+	} catch {
+		throw new NodeRequestError("Node request cannot be represented as a Web Request.");
+	}
 }
 //#endregion
 //#region src/response.ts
@@ -79,7 +188,12 @@ async function writeNodeResponse(response, target, method) {
 	target.statusCode = response.status;
 	target.statusMessage = response.statusText;
 	writeHeaders(response, target);
-	if (!response.body || method === "HEAD") {
+	if (method === "HEAD") {
+		response.body?.cancel("HEAD responses do not include a body").catch(() => void 0);
+		target.end();
+		return;
+	}
+	if (!response.body) {
 		target.end();
 		return;
 	}
@@ -95,7 +209,7 @@ async function writeNodeResponse(response, target, method) {
 			if (disconnected) return;
 			const part = await reader.read();
 			if (part.done || disconnected) break;
-			if (!target.write(Buffer.from(part.value))) await waitForDrain(target);
+			if (!target.write(part.value)) await waitForDrain(target);
 		}
 		if (!disconnected) target.end();
 	} catch (error) {
@@ -104,20 +218,25 @@ async function writeNodeResponse(response, target, method) {
 		target.destroy(error instanceof Error ? error : void 0);
 	} finally {
 		target.off("close", onClose);
+		reader.releaseLock();
 	}
 }
 //#endregion
 //#region src/handler.ts
 function minimalError(response, error) {
-	if (response.headersSent) {
+	if (response.headersSent || response.destroyed) {
 		response.destroy(error instanceof Error ? error : void 0);
 		return;
 	}
-	const clientError = error instanceof NodeRequestError;
-	response.statusCode = clientError ? 400 : 500;
-	response.statusMessage = clientError ? "Bad Request" : "Internal Server Error";
-	response.setHeader("content-type", "text/plain; charset=utf-8");
-	response.end(clientError ? "Bad Request" : "Internal Server Error");
+	try {
+		const clientError = error instanceof NodeRequestError;
+		response.statusCode = clientError ? 400 : 500;
+		response.statusMessage = clientError ? "Bad Request" : "Internal Server Error";
+		response.setHeader("content-type", "text/plain; charset=utf-8");
+		response.end(clientError ? "Bad Request" : "Internal Server Error");
+	} catch {
+		response.destroy(error instanceof Error ? error : void 0);
+	}
 }
 function attachAbort(request, response, controller) {
 	const abort = () => controller.abort();
@@ -135,68 +254,148 @@ function attachAbort(request, response, controller) {
 		response.off("close", abort);
 	};
 }
-function createNodeHandler(app, options = {}) {
+async function handleNodeRequest(app, preparedOptions, request, response, signal, cleanup, next) {
+	try {
+		const webRequest = requestFromNode(request, preparedOptions, signal);
+		await writeNodeResponse(await app.fetch(webRequest), response, request.method);
+	} catch (error) {
+		if (!next) {
+			minimalError(response, error);
+			return;
+		}
+		try {
+			next(error);
+		} catch (nextError) {
+			minimalError(response, nextError);
+		}
+	} finally {
+		cleanup();
+	}
+}
+/**
+* Wraps an `@askrjs/server` application as a Node-style request handler.
+*
+* Converts each incoming `IncomingMessage`/`ServerResponse` pair into a web
+* `Request`, dispatches it through `app.fetch`, and writes the resulting web
+* `Response` back to Node. Errors are reported to `next` when provided,
+* otherwise a minimal 400/500 response is written directly.
+*
+* @param app - The application to dispatch requests to.
+* @param options - Options controlling base URL resolution and host validation.
+* @returns A handler usable with `http.createServer` or Connect-style middleware.
+*/
+function createNodeHandler(app, options) {
+	const preparedOptions = prepareNodeHandlerOptions(options);
 	return (request, response, next) => {
 		const controller = new AbortController();
 		const cleanup = attachAbort(request, response, controller);
-		Promise.resolve().then(() => requestFromNode(request, options, controller.signal)).then((webRequest) => app.fetch(webRequest)).then((webResponse) => writeNodeResponse(webResponse, response, request.method)).catch((error) => next ? next(error) : minimalError(response, error)).finally(cleanup);
+		handleNodeRequest(app, preparedOptions, request, response, controller.signal, cleanup, next);
 	};
 }
 //#endregion
 //#region src/bind.ts
+function isLoopbackHost(host) {
+	if (host.toLowerCase() === "localhost") return true;
+	const family = isIP(host);
+	if (family === 4) return host.split(".", 1)[0] === "127";
+	if (family !== 6) return false;
+	const normalized = new URL(`http://[${host}]`).hostname;
+	return normalized === "[::1]" || normalized.startsWith("[::ffff:7f");
+}
 function resolveBindHost(options) {
 	const host = options.host ?? "127.0.0.1";
-	if (!(host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host)) && options.allowPublicBind !== true) throw new TypeError(`Refusing to bind non-loopback host ${host} without allowPublicBind: true.`);
+	if (!isLoopbackHost(host) && options.allowPublicBind !== true) throw new TypeError(`Refusing to bind non-loopback host ${host} without allowPublicBind: true.`);
 	return host;
 }
+function handlerOptionsForHost(options, host) {
+	return {
+		...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+		allowedHosts: [.../* @__PURE__ */ new Set([
+			host,
+			"localhost",
+			...options.allowedHosts ?? []
+		])]
+	};
+}
 function formatHostForUrl(host) {
 	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 //#endregion
+//#region src/server-options.ts
+function timeout(value, name) {
+	if (value === void 0) return void 0;
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative safe integer.`);
+	return value;
+}
+function applyServerTimeouts(server, options) {
+	const requestTimeout = timeout(options.requestTimeout, "requestTimeout");
+	const headersTimeout = timeout(options.headersTimeout, "headersTimeout");
+	const keepAliveTimeout = timeout(options.keepAliveTimeout, "keepAliveTimeout");
+	if (requestTimeout !== void 0) server.requestTimeout = requestTimeout;
+	if (headersTimeout !== void 0) server.headersTimeout = headersTimeout;
+	if (keepAliveTimeout !== void 0) server.keepAliveTimeout = keepAliveTimeout;
+}
+//#endregion
 //#region src/websocket.ts
 function subscribe(socket, event, listener) {
 	socket.on(event, listener);
 	return () => socket.off(event, listener);
 }
+function notify(socket, listener, ...values) {
+	try {
+		listener(...values);
+	} catch {
+		if (socket.readyState === WebSocket.OPEN) socket.close(1011, "WebSocket listener failed");
+	}
+}
 function socketLike(socket) {
 	return {
 		send: (data) => socket.send(data),
 		close: (code, reason) => socket.close(code, reason),
 		onMessage: (listener) => subscribe(socket, "message", (data, binary) => {
-			if (!binary) listener(data.toString());
+			if (!binary) notify(socket, listener, data.toString());
 			else {
 				const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
-				listener(new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
+				notify(socket, listener, new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
 			}
 		}),
-		onClose: (listener) => subscribe(socket, "close", (code, reason) => listener({
+		onClose: (listener) => subscribe(socket, "close", (code, reason) => notify(socket, listener, {
 			code,
 			reason: reason.toString(),
-			wasClean: code === 1e3
+			wasClean: code !== 1006
 		})),
-		onError: (listener) => subscribe(socket, "error", listener)
+		onError: (listener) => subscribe(socket, "error", (error) => notify(socket, listener, error))
 	};
 }
+function normalizeHttpOrigin(value) {
+	const parsed = new URL(value);
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) throw new TypeError("WebSocket origins must be HTTP or HTTPS origins.");
+	return parsed.origin;
+}
 async function readRejectionBody(response, maxBytes) {
 	const lengthHeader = response.headers.get("content-length");
 	const declaredLength = lengthHeader === null ? void 0 : Number(lengthHeader);
 	if (declaredLength !== void 0 && Number.isFinite(declaredLength) && declaredLength > maxBytes) {
-		await response.body?.cancel("WebSocket rejection body exceeded maxRejectionBodyBytes");
+		await response.body?.cancel("WebSocket rejection body exceeded maxRejectionBodyBytes").catch(() => void 0);
 		return;
 	}
 	if (!response.body) return Buffer.alloc(0);
 	const reader = response.body.getReader();
 	const chunks = [];
 	let length = 0;
-	while (true) {
-		const part = await reader.read();
-		if (part.done) return Buffer.concat(chunks, length);
-		length += part.value.byteLength;
-		if (length > maxBytes) {
-			await reader.cancel("WebSocket rejection body exceeded maxRejectionBodyBytes");
-			return;
+	try {
+		while (true) {
+			const part = await reader.read();
+			if (part.done) return Buffer.concat(chunks, length);
+			length += part.value.byteLength;
+			if (length > maxBytes) {
+				await reader.cancel("WebSocket rejection body exceeded maxRejectionBodyBytes").catch(() => void 0);
+				return;
+			}
+			chunks.push(Buffer.from(part.value));
 		}
-		chunks.push(Buffer.from(part.value));
+	} finally {
+		reader.releaseLock();
 	}
 }
 async function rejectUpgrade(socket, response, maxBodyBytes) {
@@ -204,31 +403,64 @@ async function rejectUpgrade(socket, response, maxBodyBytes) {
 	if (!buffered) response = new Response("WebSocket rejection body exceeded configured limit", { status: 500 });
 	const body = buffered ?? Buffer.from(await response.arrayBuffer());
 	const lines = [`HTTP/1.1 ${response.status} ${response.statusText || "Rejected"}`];
+	const cookies = response.headers.getSetCookie();
 	response.headers.forEach((value, name) => {
-		if (name !== "content-length" && name !== "transfer-encoding") lines.push(`${name}: ${value}`);
+		if (name !== "connection" && name !== "content-length" && name !== "set-cookie" && name !== "transfer-encoding" && name !== "upgrade") lines.push(`${name}: ${value}`);
 	});
+	for (const cookie of cookies) lines.push(`set-cookie: ${cookie}`);
 	lines.push(`content-length: ${body.byteLength}`);
 	lines.push("connection: close", "", "");
 	socket.end(Buffer.concat([Buffer.from(lines.join("\r\n")), body]));
 }
-function installWebSockets(server, app, options = {}, handlerOptions = {}) {
+function installWebSockets(server, app, options, handlerOptions) {
+	const closeTimeout = options.closeTimeout ?? 5e3;
+	if (!Number.isSafeInteger(closeTimeout) || closeTimeout < 0) throw new TypeError("WebSocket closeTimeout must be a non-negative safe integer.");
 	const maxRejectionBodyBytes = options.maxRejectionBodyBytes ?? 65536;
-	if (!Number.isInteger(maxRejectionBodyBytes) || maxRejectionBodyBytes <= 0) throw new TypeError("WebSocket maxRejectionBodyBytes must be a positive integer.");
+	if (!Number.isSafeInteger(maxRejectionBodyBytes) || maxRejectionBodyBytes <= 0) throw new TypeError("WebSocket maxRejectionBodyBytes must be a positive integer.");
+	const maxPayload = options.maxPayload ?? 1048576;
+	if (!Number.isSafeInteger(maxPayload) || maxPayload < 0) throw new TypeError("WebSocket maxPayload must be a non-negative safe integer.");
+	const preparedHandlerOptions = prepareNodeHandlerOptions(handlerOptions);
+	const configuredAllowedOrigins = options.allowedOrigins?.map((origin) => {
+		try {
+			return normalizeHttpOrigin(origin);
+		} catch {
+			throw new TypeError(`WebSocket allowedOrigins contains an invalid origin: ${origin}`);
+		}
+	});
 	const webSockets = new WebSocketServer({
 		noServer: true,
-		maxPayload: options.maxPayload ?? 1048576,
+		maxPayload,
 		perMessageDeflate: options.perMessageDeflate ?? false
 	});
-	server.on("upgrade", (request, socket, head) => {
+	const pending = /* @__PURE__ */ new Map();
+	let closing;
+	const onUpgrade = (request, socket, head) => {
+		if (closing) {
+			socket.destroy();
+			return;
+		}
 		const controller = new AbortController();
+		const abort = () => controller.abort();
+		const cleanupPending = () => {
+			pending.delete(socket);
+			socket.off("close", abort);
+			socket.off("end", abort);
+			socket.off("error", abort);
+		};
+		pending.set(socket, controller);
+		socket.once("close", abort);
+		socket.once("end", abort);
+		socket.once("error", abort);
 		let accepted;
-		Promise.resolve().then(() => requestFromNode(request, handlerOptions, controller.signal)).then(async (webRequest) => {
+		let upgraded = false;
+		Promise.resolve().then(() => requestFromNode(request, preparedHandlerOptions, controller.signal)).then(async (webRequest) => {
+			if (controller.signal.aborted) return;
 			const originHeader = request.headers.origin;
 			const origin = Array.isArray(originHeader) ? void 0 : originHeader;
-			const allowedOrigins = options.allowedOrigins ?? [new URL(webRequest.url).origin];
+			const allowedOrigins = configuredAllowedOrigins ?? [new URL(webRequest.url).origin];
 			let normalizedOrigin;
 			try {
-				normalizedOrigin = origin ? new URL(origin).origin : void 0;
+				normalizedOrigin = origin ? normalizeHttpOrigin(origin) : void 0;
 			} catch {
 				normalizedOrigin = void 0;
 			}
@@ -251,44 +483,105 @@ function installWebSockets(server, app, options = {}, handlerOptions = {}) {
 				return;
 			}
 			webSockets.handleUpgrade(request, socket, head, (webSocket) => {
+				upgraded = true;
+				cleanupPending();
+				webSocket.on("error", () => void 0);
 				webSocket.once("close", () => controller.abort());
-				Promise.resolve(accepted.handler(socketLike(webSocket), accepted.context)).catch(() => webSocket.close(1011, "WebSocket handler failed"));
+				Promise.resolve().then(() => accepted.handler(socketLike(webSocket), accepted.context)).catch(() => webSocket.close(1011, "WebSocket handler failed"));
 			});
-		}).catch(() => socket.destroy());
-	});
+		}).catch(() => socket.destroy()).finally(() => {
+			if (!upgraded) {
+				cleanupPending();
+				controller.abort();
+			}
+		});
+	};
+	server.on("upgrade", onUpgrade);
 	return { close() {
-		for (const socket of webSockets.clients) socket.close(1001, "Server shutting down");
-		webSockets.close();
+		return closing ??= new Promise((resolve, reject) => {
+			let settled = false;
+			let forceClose;
+			const complete = (error) => {
+				if (settled) return;
+				settled = true;
+				if (forceClose) clearTimeout(forceClose);
+				if (error) reject(error);
+				else resolve();
+			};
+			server.off("upgrade", onUpgrade);
+			for (const [socket, controller] of pending) {
+				controller.abort();
+				socket.destroy();
+			}
+			pending.clear();
+			for (const socket of webSockets.clients) socket.close(1001, "Server shutting down");
+			if (webSockets.clients.size > 0) {
+				forceClose = setTimeout(() => {
+					for (const socket of webSockets.clients) socket.terminate();
+					complete();
+				}, closeTimeout);
+				forceClose.unref();
+			}
+			webSockets.close(complete);
+		});
 	} };
 }
 //#endregion
 //#region src/listen.ts
+/**
+* Starts a Node HTTP server for an `@askrjs/server` application and resolves once it is listening.
+*
+* Optionally installs WebSocket support and wires up graceful shutdown on
+* `options.signal`. Unlike {@link serve}, this does not serve static assets
+* or install OS signal handlers.
+*
+* @param app - The application to serve.
+* @param options - Listen options such as port, host, timeouts, and WebSocket support.
+* @returns A promise resolving to the listening server once it has bound successfully.
+* @example
+* const server = await listen(app, { port: 3000 });
+*/
 function listen(app, options = {}) {
+	options.signal?.throwIfAborted();
 	const host = resolveBindHost(options);
-	const handlerOptions = { allowedHosts: [host, "localhost"] };
+	const handlerOptions = handlerOptionsForHost(options, host);
 	const server = createServer(createNodeHandler(app, handlerOptions));
-	if (options.requestTimeout !== void 0) server.requestTimeout = options.requestTimeout;
-	if (options.headersTimeout !== void 0) server.headersTimeout = options.headersTimeout;
-	if (options.keepAliveTimeout !== void 0) server.keepAliveTimeout = options.keepAliveTimeout;
+	applyServerTimeouts(server, options);
 	const webSockets = options.websocket ? installWebSockets(server, app, options.websocket === true ? {} : options.websocket, handlerOptions) : void 0;
 	if (webSockets) {
 		const nativeClose = server.close.bind(server);
 		server.close = ((callback) => {
-			webSockets.close();
-			return nativeClose(callback);
+			let remaining = 2;
+			let closeError;
+			const complete = (error) => {
+				closeError ??= error;
+				remaining -= 1;
+				if (remaining === 0) callback?.(closeError);
+			};
+			nativeClose(complete);
+			webSockets.close().then(() => complete(), complete);
+			return server;
 		});
 	}
 	const close = () => server.close();
-	options.signal?.addEventListener("abort", close, { once: true });
-	server.once("close", () => options.signal?.removeEventListener("abort", close));
+	const abortListener = options.signal ? addAbortListener(options.signal, close) : void 0;
+	const disposeAbortListener = () => abortListener?.[Symbol.dispose]();
+	server.once("close", disposeAbortListener);
 	return new Promise((resolve, reject) => {
+		const onClose = () => {
+			server.off("error", onError);
+			reject(options.signal?.reason ?? /* @__PURE__ */ new Error("Node server closed before it started listening."));
+		};
 		const onError = (error) => {
-			options.signal?.removeEventListener("abort", close);
+			server.off("close", onClose);
+			disposeAbortListener();
 			reject(error);
 		};
 		server.once("error", onError);
+		server.once("close", onClose);
 		server.listen(options.port ?? 0, host, options.backlog, () => {
 			server.off("error", onError);
+			server.off("close", onClose);
 			resolve(server);
 		});
 	});
@@ -296,7 +589,9 @@ function listen(app, options = {}) {
 //#endregion
 //#region src/serve.ts
 const mimeTypes = {
+	".avif": "image/avif",
 	".css": "text/css; charset=utf-8",
+	".gif": "image/gif",
 	".html": "text/html; charset=utf-8",
 	".ico": "image/x-icon",
 	".jpeg": "image/jpeg",
@@ -304,8 +599,14 @@ const mimeTypes = {
 	".js": "text/javascript; charset=utf-8",
 	".json": "application/json; charset=utf-8",
 	".mjs": "text/javascript; charset=utf-8",
+	".mp4": "video/mp4",
+	".pdf": "application/pdf",
 	".png": "image/png",
 	".svg": "image/svg+xml",
+	".txt": "text/plain; charset=utf-8",
+	".wasm": "application/wasm",
+	".webm": "video/webm",
+	".webmanifest": "application/manifest+json; charset=utf-8",
 	".webp": "image/webp",
 	".woff": "font/woff",
 	".woff2": "font/woff2"
@@ -317,13 +618,36 @@ function isWithinRoot(root, candidate) {
 	const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
 	return candidate === root || candidate.startsWith(prefix);
 }
+/**
+* Serves an `@askrjs/server` application over Node HTTP, with optional static
+* asset serving, WebSocket support, and graceful shutdown on OS signals or an
+* abort signal.
+*
+* Requests for paths with a file extension are first checked against
+* `options.assets.root` (path-traversal safe, following symlinks) and served
+* directly with appropriate `content-type`/`cache-control` headers before
+* falling back to the application handler. HTML responses from the
+* application get a `no-cache` header when they don't already set
+* `cache-control`.
+*
+* @param app - The application to serve; may expose an optional `close()` for cleanup.
+* @param options - Serve options such as port, host, static assets, and shutdown signals.
+* @returns The served application, including its bound `url` and a `close()` for shutdown.
+* @example
+* const app = await serve(myApp, { port: 3000, assets: { root: "./public" } });
+* // ...
+* await app.close();
+*/
 async function serve(app, options = {}) {
+	options.signal?.throwIfAborted();
 	const host = resolveBindHost(options);
 	const root = options.assets ? await realpath(resolve(options.assets.root)) : void 0;
-	const handlerOptions = { allowedHosts: [host, "localhost"] };
+	const handlerOptions = handlerOptionsForHost(options, host);
+	const preparedHandlerOptions = prepareNodeHandlerOptions(handlerOptions);
 	const applicationHandler = createNodeHandler({ async fetch(request, dispatchOptions) {
 		const result = await app.fetch(request, dispatchOptions);
-		if (!result.headers.has("cache-control") && result.headers.get("content-type")?.includes("text/html")) {
+		const contentType = result.headers.get("content-type");
+		if (!result.headers.has("cache-control") && contentType !== null && /^text\/html(?:;|$)/iu.test(contentType)) {
 			const headers = new Headers(result.headers);
 			headers.set("cache-control", "no-cache");
 			return new Response(result.body, {
@@ -335,25 +659,29 @@ async function serve(app, options = {}) {
 		return result;
 	} }, handlerOptions);
 	const server = createServer(async (request, response) => {
+		if (!root) {
+			applicationHandler(request, response);
+			return;
+		}
 		let pathname;
 		try {
-			pathname = decodeURIComponent(resolveNodeRequestUrl(request, handlerOptions).pathname);
+			pathname = decodeURIComponent(resolveNodeRequestUrl(request, preparedHandlerOptions).pathname);
 		} catch {
 			response.writeHead(400, { "content-type": "text/plain; charset=utf-8" }).end("Bad Request");
 			return;
 		}
 		const method = request.method ?? "GET";
-		if (root && (method === "GET" || method === "HEAD") && isAssetPath(pathname)) {
+		if ((method === "GET" || method === "HEAD") && isAssetPath(pathname)) {
 			const extension = extname(pathname).toLowerCase();
 			const unresolvedCandidate = resolve(root, `.${pathname}`);
 			const inside = isWithinRoot(root, unresolvedCandidate);
 			let candidate;
 			let file;
 			if (inside && extension !== ".map") try {
-				const resolvedCandidate = await realpath(unresolvedCandidate);
+				const [resolvedCandidate, candidateFile] = await Promise.all([realpath(unresolvedCandidate), stat(unresolvedCandidate)]);
 				if (isWithinRoot(root, resolvedCandidate)) {
 					candidate = resolvedCandidate;
-					file = await stat(candidate);
+					file = candidateFile;
 				}
 			} catch {
 				candidate = void 0;
@@ -373,47 +701,64 @@ async function serve(app, options = {}) {
 				"x-content-type-options": "nosniff"
 			});
 			if (method === "HEAD") response.end();
-			else createReadStream(candidate).pipe(response);
+			else pipeline(createReadStream(candidate), response, () => void 0);
 			return;
 		}
 		applicationHandler(request, response);
 	});
-	if (options.requestTimeout !== void 0) server.requestTimeout = options.requestTimeout;
-	if (options.headersTimeout !== void 0) server.headersTimeout = options.headersTimeout;
-	if (options.keepAliveTimeout !== void 0) server.keepAliveTimeout = options.keepAliveTimeout;
+	applyServerTimeouts(server, options);
 	const webSockets = options.websocket ? installWebSockets(server, app, options.websocket === true ? {} : options.websocket, handlerOptions) : void 0;
 	let closing;
+	let serverClosed = false;
+	server.once("close", () => {
+		serverClosed = true;
+	});
 	const signals = options.signals === false ? [] : options.signals ?? ["SIGINT", "SIGTERM"];
+	let abortListener;
 	const removeListeners = () => {
-		options.signal?.removeEventListener("abort", shutdown);
+		abortListener?.[Symbol.dispose]();
 		for (const signal of signals) process.removeListener(signal, shutdown);
 	};
-	const close = () => closing ??= new Promise((resolveClose, rejectClose) => {
+	const close = () => closing ??= (async () => {
 		removeListeners();
-		webSockets?.close();
-		const finish = async (serverError) => {
-			try {
-				await app.close?.();
-				if (serverError) rejectClose(serverError);
-				else resolveClose();
-			} catch (error) {
-				rejectClose(error);
+		const closeServer = new Promise((resolveClose, rejectClose) => {
+			if (serverClosed) {
+				resolveClose();
+				return;
 			}
-		};
-		if (!server.listening) finish();
-		else server.close((error) => void finish(error));
-	});
+			server.close((error) => error ? rejectClose(error) : resolveClose());
+		});
+		const errors = (await Promise.allSettled([closeServer, webSockets?.close()])).filter((result) => result.status === "rejected").map((result) => result.reason);
+		try {
+			await app.close?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "Failed to close served application.");
+	})();
 	const shutdown = () => void close().catch(() => void 0);
-	options.signal?.addEventListener("abort", shutdown, { once: true });
+	if (options.signal) abortListener = addAbortListener(options.signal, shutdown);
 	for (const signal of signals) process.once(signal, shutdown);
 	await new Promise((resolveListen, rejectListen) => {
-		server.once("error", rejectListen);
+		const onError = (error) => {
+			server.off("close", onClose);
+			rejectListen(error);
+		};
+		const onClose = () => {
+			server.off("error", onError);
+			rejectListen(options.signal?.reason ?? /* @__PURE__ */ new Error("Node server closed before it started listening."));
+		};
+		server.once("error", onError);
+		server.once("close", onClose);
 		server.listen(options.port ?? 0, host, options.backlog, () => {
-			server.removeListener("error", rejectListen);
+			server.off("error", onError);
+			server.off("close", onClose);
 			resolveListen();
 		});
-	}).catch((error) => {
+	}).catch(async (error) => {
 		removeListeners();
+		await close().catch(() => void 0);
 		throw error;
 	});
 	const address = server.address();
@@ -428,4 +773,4 @@ async function serve(app, options = {}) {
 	});
 }
 //#endregion
-export { createNodeHandler, listen, serve };
+export { CLIENT_ADDRESS_HEADER, createNodeHandler, listen, normalizeClientAddress, serve };