@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/server/serverHelpers/Headers.ts

@@ -31,6 +31,10 @@ export class Headers extends Map<string, [string, string | string[]]> {
 		if (typeof name !== 'string') name = '' + name;
 		return super.has(name.toLowerCase());
 	}
+	delete(name) {
+		if (typeof name !== 'string') name = '' + name;
+		return super.delete(name.toLowerCase());
+	}
 	setIfNone(name, value) {
 		if (typeof name !== 'string') name = '' + name;
 		if (typeof value !== 'string') value = '' + value;
@@ -159,3 +163,134 @@ export function toWriteHeadHeaders(headers: any): any {
 	}
 	return result;
 }
+
+// RFC 9111 cache-scope directives; boundaries on both sides so a token like `public-foo` doesn't match.
+export const SHARED_CACHE_OPTIN = /(^|[,\s])(public|s-maxage)($|[\s,;=])/i;
+export const PRIVATE_SCOPE = /(^|[,\s])(private|no-store)($|[\s,;=])/i;
+
+function headerValueString(value: unknown): string {
+	if (value == null) return '';
+	return Array.isArray(value) ? value.join(', ') : String(value);
+}
+
+/**
+ * Folds the middleware chain's response headers into the headers a fallback server produced for the
+ * same request.
+ *
+ * Bun and uWS construct a new response from legacy Fastify when the chain declines a request, so the
+ * chain's credential-dependent cache policy must be merged explicitly. Fastify wins headers it set,
+ * `Vary` is unioned, and private cache scope is re-applied unless the final response explicitly opts
+ * into RFC 9111 shared caching with `public` or `s-maxage`.
+ */
+export function mergeChainHeadersIntoFallback<
+	T extends {
+		get(name: string): any;
+		set(name: string, value: any): any;
+		has(name: string): boolean;
+		append?(name: string, value: any): any;
+	},
+>(chainHeaders: any, finalHeaders: T): T {
+	if (!chainHeaders?.[Symbol.iterator]) return finalHeaders;
+	const chainVary = headerValueString(chainHeaders.get('Vary'));
+	const chainCacheControl = headerValueString(chainHeaders.get('Cache-Control'));
+	for (const [name, value] of chainHeaders) {
+		const lowerName = String(name).toLowerCase();
+		if (lowerName === 'vary' || lowerName === 'cache-control') continue;
+		if (finalHeaders.has(name)) {
+			if (lowerName === 'set-cookie') {
+				const existing = (finalHeaders as any).getSetCookie?.() ?? finalHeaders.get(name);
+				const existingValues = new Set((Array.isArray(existing) ? existing : [existing]).map(String));
+				const values = Array.isArray(value) ? value : [value];
+				for (const single of values) {
+					if (!existingValues.has(String(single))) appendHeader(finalHeaders, name, single, false);
+				}
+			}
+			continue;
+		}
+		if (Array.isArray(value)) {
+			for (const single of value) appendHeader(finalHeaders, name, single, lowerName !== 'set-cookie');
+		} else finalHeaders.set(name, value);
+	}
+	for (const token of chainVary.split(',')) {
+		const trimmed = token.trim();
+		if (trimmed) addVaryHeader(finalHeaders as any, trimmed);
+	}
+	if (chainCacheControl) {
+		const finalCacheControl = headerValueString(finalHeaders.get('Cache-Control'));
+		if (!finalCacheControl) finalHeaders.set('Cache-Control', chainCacheControl);
+		else if (
+			PRIVATE_SCOPE.test(chainCacheControl) &&
+			!PRIVATE_SCOPE.test(finalCacheControl) &&
+			!SHARED_CACHE_OPTIN.test(finalCacheControl)
+		)
+			finalHeaders.set('Cache-Control', finalCacheControl + ', private');
+	}
+	return finalHeaders;
+}
+
+function nodeResponseHeaders(nodeResponse: any) {
+	return {
+		get: (name: string) => nodeResponse.getHeader(name),
+		set: (name: string, value: any) => nodeResponse.setHeader(name, value),
+		has: (name: string) => nodeResponse.hasHeader(name),
+		append: (name: string, value: any, commaDelimited?: boolean) => {
+			const existing = nodeResponse.getHeader(name);
+			if (existing == null) return nodeResponse.setHeader(name, value);
+			if (commaDelimited)
+				return nodeResponse.setHeader(name, (Array.isArray(existing) ? existing.join(', ') : existing) + ', ' + value);
+			return nodeResponse.setHeader(name, Array.isArray(existing) ? [...existing, value] : [existing, value]);
+		},
+	};
+}
+
+export function applyWriteHeadHeaders(nodeResponse: any, headers: any): void {
+	const suppliedHeaders = new Map<string, { name: string; value: any }>();
+	const addHeader = (name: string, value: any) => {
+		const key = String(name).toLowerCase();
+		const supplied = suppliedHeaders.get(key);
+		if (!supplied) {
+			suppliedHeaders.set(key, { name, value });
+			return;
+		}
+		const values = Array.isArray(supplied.value) ? supplied.value : [supplied.value];
+		supplied.value = Array.isArray(value) ? values.concat(value) : values.concat([value]);
+	};
+	if (Array.isArray(headers)) {
+		if (Array.isArray(headers[0])) {
+			for (const [name, value] of headers) addHeader(name, value);
+		} else {
+			for (let i = 0; i + 1 < headers.length; i += 2) addHeader(headers[i], headers[i + 1]);
+		}
+	} else {
+		for (const name of Object.keys(headers)) {
+			const value = headers[name];
+			if (value != null) addHeader(name, value);
+		}
+	}
+	for (const { name, value } of suppliedHeaders.values()) nodeResponse.setHeader(name, value);
+}
+
+/**
+ * Node's counterpart to the Bun and uWS fallback bridges: the chain's headers go onto the
+ * `ServerResponse` before legacy Fastify runs, so a Fastify route that sets `Cache-Control` or `Vary`
+ * replaces them outright and can make a credential-dependent response shared-cacheable (#1565).
+ * Reconciliation therefore runs at `writeHead` — the last point the header set is still mutable, and
+ * the one Node also routes implicit headers through — using the same policy as the other two bridges.
+ */
+export function bridgeChainHeadersToNodeResponse(chainHeaders: any, nodeResponse: any): void {
+	if (!chainHeaders?.[Symbol.iterator]) return;
+	for (const [name, value] of chainHeaders) nodeResponse.setHeader(name, value);
+	const originalWriteHead = nodeResponse.writeHead;
+	nodeResponse.writeHead = function (statusCode: number, statusMessage?: any, headers?: any) {
+		if (this.headersSent) return originalWriteHead.apply(this, arguments as any);
+		if (statusMessage != null && typeof statusMessage !== 'string') {
+			headers = statusMessage;
+			statusMessage = undefined;
+		}
+		if (headers) applyWriteHeadHeaders(this, headers);
+		mergeChainHeadersIntoFallback(chainHeaders, nodeResponseHeaders(this));
+		return statusMessage === undefined
+			? originalWriteHead.call(this, statusCode)
+			: originalWriteHead.call(this, statusCode, statusMessage);
+	};
+}

package/server/serverHelpers/NodeAdapterResponse.ts

@@ -0,0 +1,221 @@
+import { STATUS_CODES } from 'node:http';
+import type {
+	IncomingMessage as NodeIncomingMessage,
+	OutgoingHttpHeader,
+	OutgoingHttpHeaders,
+	ServerResponse as NodeServerResponse,
+} from 'node:http';
+import type { Socket } from 'node:net';
+import { PassThrough } from 'node:stream';
+import { Headers as ResponseHeaders, applyWriteHeadHeaders } from './Headers.ts';
+
+export interface AdaptedResponse {
+	status: number;
+	headers: ResponseHeaders;
+	body: PassThrough;
+}
+
+class HeadersSentError extends Error {
+	code = 'ERR_HTTP_HEADERS_SENT';
+	constructor(action: string) {
+		super(`Cannot ${action} headers after they are sent to the client`);
+	}
+}
+
+class UnsupportedResponseMethodError extends Error {
+	constructor(method: string) {
+		super(`${method}() is not supported on a withNodeAdapter() response`);
+	}
+}
+
+const ignoreError = () => {};
+
+export class NodeAdapterResponse extends PassThrough implements NodeServerResponse {
+	statusCode = 200;
+	statusMessage = '';
+	strictContentLength = false;
+	chunkedEncoding = false;
+	shouldKeepAlive = true;
+	useChunkedEncodingByDefault = true;
+	sendDate = true;
+	readonly req: NodeIncomingMessage;
+	readonly socket: Socket | null;
+	#headers = new ResponseHeaders();
+	#committedStatus: number | undefined;
+	#headerText: string | undefined;
+	#nodeResponse: NodeServerResponse | undefined;
+	#resolve: (response: AdaptedResponse) => void;
+	#reject: (reason: unknown) => void;
+
+	constructor(
+		req: NodeIncomingMessage,
+		nodeResponse: NodeServerResponse | undefined,
+		resolve: (response: AdaptedResponse) => void,
+		reject: (reason: unknown) => void
+	) {
+		super();
+		this.req = req;
+		this.socket = req.socket ?? null;
+		this.#nodeResponse = nodeResponse;
+		this.#resolve = resolve;
+		this.#reject = reject;
+		this.on('error', ignoreError);
+		if (typeof nodeResponse?.on === 'function') {
+			const forward = (...args: any[]) => this.emit('timeout', ...args);
+			let forwarding = false;
+			const syncForwarding = (wanted: boolean) => {
+				if (wanted === forwarding) return;
+				forwarding = wanted;
+				if (wanted) nodeResponse.on('timeout', forward);
+				else nodeResponse.removeListener('timeout', forward);
+			};
+			const onNewListener = (event: string | symbol) => event === 'timeout' && syncForwarding(true);
+			const onRemoveListener = (event: string | symbol) =>
+				event === 'timeout' && syncForwarding(this.listenerCount('timeout') > 0);
+			this.on('newListener', onNewListener);
+			this.on('removeListener', onRemoveListener);
+			this.once('close', () => {
+				syncForwarding(false);
+				this.removeListener('newListener', onNewListener);
+				this.removeListener('removeListener', onRemoveListener);
+			});
+		}
+	}
+
+	get headersSent() {
+		return this.#committedStatus !== undefined;
+	}
+	get finished() {
+		return this.writableEnded;
+	}
+	get connection() {
+		return this.socket;
+	}
+	get _header(): string | null {
+		if (this.#committedStatus === undefined) return null;
+		if (this.#headerText === undefined) {
+			let text = `HTTP/1.1 ${this.#committedStatus} ${this.statusMessage}\r\n`;
+			for (const [name, value] of this.#headers) {
+				if (Array.isArray(value)) for (const entry of value) text += `${name}: ${entry}\r\n`;
+				else text += `${name}: ${value}\r\n`;
+			}
+			this.#headerText = text + '\r\n';
+		}
+		return this.#headerText;
+	}
+
+	setHeader(name: string, value: number | string | readonly string[]) {
+		if (this.headersSent) throw new HeadersSentError('set');
+		this.#headers.set(name, value);
+		return this;
+	}
+	setHeaders(headers: Headers | Map<string, number | string | readonly string[]> | ResponseHeaders) {
+		let cookies: string[] | undefined;
+		for (const [name, value] of headers) {
+			if (name.toLowerCase() !== 'set-cookie') this.setHeader(name, value);
+			else if (Array.isArray(value)) (cookies ??= []).push(...value);
+			else (cookies ??= []).push(String(value));
+		}
+		if (cookies) this.setHeader('set-cookie', cookies);
+		return this;
+	}
+	appendHeader(name: string, value: string | readonly string[]) {
+		if (this.headersSent) throw new HeadersSentError('append');
+		if (Array.isArray(value)) for (const entry of value) this.#headers.append(name, entry);
+		else this.#headers.append(name, value);
+		return this;
+	}
+	getHeader(name: string) {
+		return this.#headers.get(name);
+	}
+	getHeaders() {
+		const headers: OutgoingHttpHeaders = Object.create(null);
+		for (const [name, value] of this.#headers) headers[name.toLowerCase()] = value;
+		return headers;
+	}
+	getHeaderNames() {
+		return [...this.#headers.keys()];
+	}
+	hasHeader(name: string) {
+		return this.#headers.has(name);
+	}
+	removeHeader(name: string) {
+		if (this.headersSent) throw new HeadersSentError('remove');
+		this.#headers.delete(name);
+	}
+
+	writeHead(statusCode: number, statusMessage?: string, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): this;
+	writeHead(statusCode: number, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): this;
+	writeHead(
+		statusCode: number,
+		statusMessageOrHeaders?: string | OutgoingHttpHeaders | OutgoingHttpHeader[],
+		headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]
+	) {
+		if (this.headersSent) throw new HeadersSentError('write');
+		this.statusCode = statusCode;
+		if (typeof statusMessageOrHeaders === 'string') this.statusMessage = statusMessageOrHeaders;
+		else {
+			this.statusMessage ||= STATUS_CODES[statusCode] || 'unknown';
+			// writeHead(302, undefined, headers) is the three-argument form with the status message
+			// omitted; the hole must not erase the headers the third argument carries.
+			headers ??= statusMessageOrHeaders;
+		}
+		if (headers) applyWriteHeadHeaders(this, headers);
+		this.#committedStatus = statusCode;
+		this.#resolve({ status: statusCode, headers: this.#headers, body: this });
+		return this;
+	}
+	_implicitHeader() {
+		this.writeHead(this.statusCode);
+	}
+	flushHeaders() {
+		if (!this.headersSent) this._implicitHeader();
+	}
+
+	write(
+		chunk: unknown,
+		encoding?: BufferEncoding | ((error?: Error | null) => void),
+		callback?: (error?: Error | null) => void
+	) {
+		if (!this.headersSent) this._implicitHeader();
+		return super.write(chunk, encoding as BufferEncoding, callback);
+	}
+	end(chunk?: unknown, encoding?: BufferEncoding | (() => void), callback?: () => void) {
+		if (!this.headersSent) this._implicitHeader();
+		return super.end(chunk, encoding as BufferEncoding, callback);
+	}
+	_destroy(error: Error | null, callback: (error?: Error | null) => void) {
+		if (!this.headersSent) this.#reject(error ?? new Error('Response destroyed before headers were sent'));
+		callback(error);
+	}
+
+	setTimeout(msecs: number, callback?: () => void) {
+		if (callback) this.on('timeout', callback);
+		const nodeResponse = this.#nodeResponse;
+		if (typeof nodeResponse?.setTimeout !== 'function') return this;
+		nodeResponse.setTimeout(msecs);
+		return this;
+	}
+	writeContinue(callback?: () => void) {
+		if (typeof this.#nodeResponse?.writeContinue === 'function') this.#nodeResponse.writeContinue(callback);
+		else callback?.();
+	}
+	writeProcessing(callback?: () => void) {
+		if (typeof this.#nodeResponse?.writeProcessing === 'function') this.#nodeResponse.writeProcessing(callback);
+		else callback?.();
+	}
+	writeEarlyHints(hints: Record<string, string | string[]>, callback?: () => void) {
+		if (typeof this.#nodeResponse?.writeEarlyHints === 'function') this.#nodeResponse.writeEarlyHints(hints, callback);
+		else callback?.();
+	}
+	// Trailers need chunked encoding on the wire, which Harper's response layer owns; dropping one silently (a Digest, say) is worse than failing.
+	addTrailers(): never {
+		throw new UnsupportedResponseMethodError('addTrailers');
+	}
+	assignSocket(): never {
+		throw new UnsupportedResponseMethodError('assignSocket');
+	}
+	detachSocket(): never {
+		throw new UnsupportedResponseMethodError('detachSocket');
+	}
+}

package/server/serverHelpers/Request.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage as NodeIncomingMessage, ServerResponse as NodeServerResponse } from 'node:http';
 import type { Socket } from 'node:net';
 import { TLSSocket } from 'node:tls';
-import { EventEmitter } from 'node:events';
-import { Readable, PassThrough } from 'node:stream';
+import { Readable } from 'node:stream';
 import { Headers as ResponseHeaders } from './Headers.ts';
+import { NodeAdapterResponse, type AdaptedResponse } from './NodeAdapterResponse.ts';
 import type { ConnectionInfo } from './proxyProtocol.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
 
 export const isBun = typeof globalThis.Bun !== 'undefined';
 
@@ -178,10 +179,8 @@ export class Request {
 	 * status, headers, and body, resolving the returned promise as soon as headers are available with a
 	 * streaming body that can be piped back through the Harper middleware chain.
 	 *
-	 * **Important:** The resolved `body` PassThrough must have an `error` listener attached (or be piped
-	 * to a destination that handles errors) before it is consumed. If the underlying connection is reset
-	 * after headers are sent, the body stream is destroyed with an error — without a listener, Node.js
-	 * will throw an uncaught exception.
+	 * Consume the returned body with `pipeline()`, `finished()` or async iteration so stored stream errors
+	 * and premature closes are reported.
 	 *
 	 * Example:
 	 *   server.http((request, next) =>
@@ -190,11 +189,13 @@ export class Request {
 	 */
 	withNodeAdapter(
 		handler: (request: NodeIncomingMessage, response: NodeServerResponse) => void | Promise<void>
-	): Promise<{ status: number; headers: ResponseHeaders; body: PassThrough }> {
-		// Flat headers object matching IncomingMessage.headers format (lowercase keys)
-		const reqHeaders: Record<string, string | string[]> = Object.create(null);
+	): Promise<AdaptedResponse> {
+		const reqHeaders: Record<string, string | string[]> = {};
 		for (const [key, value] of this.headers) {
-			reqHeaders[key.toLowerCase()] = value;
+			const lowerKey = key.toLowerCase();
+			if (lowerKey === '__proto__')
+				Object.defineProperty(reqHeaders, lowerKey, { value, configurable: true, enumerable: true, writable: true });
+			else reqHeaders[lowerKey] = value;
 		}
 
 		// Proxy the underlying IncomingMessage so body streaming works, but expose
@@ -209,131 +210,32 @@ export class Request {
 			},
 		}) as NodeIncomingMessage;
 
-		let resolveResponse!: (value: { status: number; headers: ResponseHeaders; body: PassThrough }) => void;
-		let rejectResponse!: (reason: unknown) => void;
-		const response = new Promise<{ status: number; headers: ResponseHeaders; body: PassThrough }>((resolve, reject) => {
-			resolveResponse = resolve;
-			rejectResponse = reject;
+		let nodeRes!: NodeAdapterResponse;
+		const response = new Promise<AdaptedResponse>((resolve, reject) => {
+			nodeRes = new NodeAdapterResponse(nodeReq, this._nodeResponse, resolve, reject);
 		});
 
-		const responseBody = new PassThrough();
-		const capturedHeaders = new ResponseHeaders();
-		let headersFlushed = false;
-		let nodeRes: ReturnType<typeof Object.assign> & NodeServerResponse;
+		const signal = this.signal;
+		const onAbort = () => nodeRes.destroy(nodeRes.headersSent ? undefined : signal.reason);
+		if (signal.aborted) onAbort();
+		else {
+			signal.addEventListener('abort', onAbort, { once: true });
+			nodeRes.once('close', () => signal.removeEventListener('abort', onAbort));
+		}
 
-		const flushHeaders = () => {
-			if (!headersFlushed) {
-				headersFlushed = true;
-				nodeRes.headersSent = true;
-				resolveResponse({ status: nodeRes.statusCode as number, headers: capturedHeaders, body: responseBody });
-			}
+		const onHandlerFailure = (error: Error) => {
+			if (!nodeRes.writableEnded) nodeRes.destroy(error);
+			else harperLogger.warn('withNodeAdapter handler failed after ending its response', error);
 		};
-
-		const applyHeaders = (hdrs: object | unknown[]) => {
-			if (Array.isArray(hdrs)) {
-				if (hdrs.length > 0 && Array.isArray(hdrs[0])) {
-					for (const [name, value] of hdrs as [string, string][]) capturedHeaders.set(name, value);
-				} else {
-					for (let i = 0; i < hdrs.length; i += 2) capturedHeaders.set(hdrs[i] as string, hdrs[i + 1] as string);
-				}
-			} else {
-				for (const [k, v] of Object.entries(hdrs)) capturedHeaders.set(k, v as string);
-			}
-		};
-
-		nodeRes = Object.assign(new EventEmitter(), {
-			statusCode: 200 as number,
-			statusMessage: '',
-			headersSent: false,
-			writable: true,
-			writableEnded: false,
-			writableFinished: false,
-			socket: this._nodeRequest.socket,
-
-			setHeader(name: string, value: string | number | string[]) {
-				if (Array.isArray(value)) {
-					// Use set() for first value (overwrites any existing entry) then append() for
-					// the rest so multiple values — critical for Set-Cookie — are preserved as an
-					// array rather than collapsed into a single comma-joined string.
-					if (value.length > 0) {
-						capturedHeaders.set(name, String(value[0]));
-						for (let i = 1; i < value.length; i++) capturedHeaders.append(name, String(value[i]));
-					}
-				} else {
-					capturedHeaders.set(name, String(value));
-				}
-				return nodeRes;
-			},
-			getHeader(name: string) {
-				return capturedHeaders.get(name);
-			},
-			getHeaders() {
-				return Object.fromEntries(capturedHeaders);
-			},
-			hasHeader(name: string) {
-				return capturedHeaders.has(name);
-			},
-			removeHeader(name: string) {
-				capturedHeaders.delete(name);
-			},
-			flushHeaders() {
-				flushHeaders();
-			},
-			writeHead(statusCode: number, statusMessageOrHeaders?: string | object, maybeHeaders?: object) {
-				if (headersFlushed) return nodeRes;
-				nodeRes.statusCode = statusCode;
-				const hdrs = typeof statusMessageOrHeaders === 'string' ? maybeHeaders : statusMessageOrHeaders;
-				if (hdrs) applyHeaders(hdrs as object | unknown[]);
-				flushHeaders();
-				return nodeRes;
-			},
-			write(
-				chunk: unknown,
-				encoding?: BufferEncoding | ((error?: Error | null) => void),
-				callback?: (error?: Error | null) => void
-			) {
-				flushHeaders();
-				if (typeof encoding === 'function') return responseBody.write(chunk as any, encoding);
-				return responseBody.write(chunk as any, encoding, callback);
-			},
-			end(chunk?: unknown, encoding?: BufferEncoding | (() => void), callback?: () => void) {
-				flushHeaders();
-				nodeRes.writableEnded = true;
-				if (typeof chunk === 'function') responseBody.end(chunk as () => void);
-				else if (typeof encoding === 'function') responseBody.end(chunk as any, encoding);
-				else responseBody.end(chunk as any, encoding, callback);
-				return nodeRes;
-			},
-			destroy(error?: Error) {
-				if (!headersFlushed) {
-					if (error) rejectResponse(error);
-					else rejectResponse(new Error('Response destroyed before headers were sent'));
-					// The error has been forwarded to the response promise; suppress the
-					// PassThrough 'error' event for this one destroy call so Node doesn't
-					// throw due to having no other listeners.
-					responseBody.once('error', () => {});
-				}
-				responseBody.destroy(error);
-				return nodeRes;
-			},
-		}) as unknown as NodeServerResponse;
-
-		responseBody.on('finish', () => {
-			nodeRes.writableFinished = true;
-			(nodeRes as unknown as EventEmitter).emit('finish');
-		});
-		responseBody.on('drain', () => {
-			(nodeRes as unknown as EventEmitter).emit('drain');
-		});
-		responseBody.on('close', () => {
-			(nodeRes as unknown as EventEmitter).emit('close');
-		});
-
-		const handlerResult = handler(nodeReq, nodeRes);
-		if (handlerResult != null && typeof (handlerResult as unknown as Promise<void>).then === 'function') {
-			(handlerResult as unknown as Promise<void>).catch((err: unknown) => {
-				if (!headersFlushed) rejectResponse(err);
-			});
+		let handlerResult: void | Promise<void>;
+		try {
+			handlerResult = handler(nodeReq, nodeRes);
+		} catch (error) {
+			onHandlerFailure(error as Error);
+			return response;
+		}
+		if (typeof (handlerResult as Promise<void>)?.then === 'function') {
+			Promise.resolve(handlerResult).catch(onHandlerFailure);
 		}
 		return response;
 	}