@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.2

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;
 	}

package/server/serverHelpers/contentTypes.ts

@@ -10,6 +10,10 @@ import * as envMgr from '../../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
 import * as YAML from 'yaml';
 import { logger } from '../../utility/logging/logger.ts';
+import {
+	errorToString as harperErrorToString,
+	errorForLog as harperErrorForLog,
+} from '../../utility/logging/harper_logger.ts';
 import { Blob } from '../../resources/blob.ts';
 // TODO: Only load this if fastify is loaded
 import fp from 'fastify-plugin';
@@ -17,6 +21,36 @@ import { parseMultipartRequest } from './multipartParser.ts';
 const SERIALIZATION_BIGINT = envMgr.get(CONFIG_PARAMS.SERIALIZATION_BIGINT) !== false;
 const JSONStringify = SERIALIZATION_BIGINT ? stringify : JSON.stringify;
 const JSONParse = SERIALIZATION_BIGINT ? parse : JSON.parse;
+const streamStartup = Symbol('streamStartup');
+const serializedStreamError = Symbol('serializedStreamError');
+
+type StreamStartup = {
+	result: Promise<{ failed?: true; error?: unknown }>;
+	abort: () => void;
+	start: () => void;
+	cancel?: () => void;
+};
+
+function streamErrorRecord(error: any) {
+	let name = 'Error';
+	let message;
+	try {
+		const code = error?.code;
+		if (typeof code === 'string' || typeof code === 'number') name = String(code);
+		else if (typeof error?.constructor?.name === 'string') name = error.constructor.name;
+		else if (typeof error?.name === 'string') name = error.name;
+	} catch {}
+	try {
+		if (typeof error?.message === 'string') message = error.message;
+	} catch {}
+	message ??= harperErrorToString(error);
+	const record: { error: string; message: string; status?: number } = { error: name, message };
+	try {
+		const status = error?.statusCode ?? error?.status;
+		if (typeof status === 'number') record.status = status;
+	} catch {}
+	return record;
+}
 
 const PUBLIC_ENCODE_OPTIONS = {
 	useRecords: false,
@@ -103,9 +137,14 @@ mediaTypes.set('text/yaml', {
 });
 
 const ndjsonHandler = {
-	serializeStream(data: any) {
+	serializeStream(data: any, _response?: Response, request?: any) {
 		if (data?.[Symbol.iterator] || data?.[Symbol.asyncIterator]) {
-			return Readable.from(transformIterable(data, (msg: any) => JSONStringify(msg) + '\n'));
+			return errorFrameStream(
+				data,
+				(msg: any) => JSONStringify(msg) + '\n',
+				(error) => JSONStringify({ $harperStreamError: streamErrorRecord(error) }) + '\n',
+				request?.method === 'GET'
+			);
 		}
 		return JSONStringify(data) + '\n';
 	},
@@ -132,9 +171,14 @@ function serializeSSEData(data: any) {
 
 mediaTypes.set('text/event-stream', {
 	// Server-Sent Events (SSE)
-	serializeStream: function (iterable) {
+	serializeStream: function (iterable, _response?: Response, request?: any) {
 		// create a readable stream that we use to stream out events from our subscription
-		return Readable.from(transformIterable(iterable, this.serialize));
+		return errorFrameStream(
+			iterable,
+			this.serialize,
+			(error) => this.serialize({ event: 'harper-error', data: streamErrorRecord(error) }),
+			request?.method === 'GET'
+		);
 	},
 	serialize: function (message) {
 		if (message.acknowledge) message.acknowledge();
@@ -396,7 +440,12 @@ export function serialize(responseData, request, responseObject) {
 			(responseData[Symbol.iterator] || responseData[Symbol.asyncIterator]) &&
 			serializer.serializer.serializeStream
 		) {
-			if (responseData.mapError) {
+			if (
+				responseData.mapError &&
+				serializer.type !== 'application/x-ndjson' &&
+				serializer.type !== 'application/ndjson' &&
+				serializer.type !== 'text/event-stream'
+			) {
 				// indicate that we want iterator errors to be returned so we can serialize them in a meaningful way, if possible
 				const getColumns = responseData.getColumns;
 				responseData = responseData.mapError((error) => {
@@ -407,9 +456,10 @@ export function serialize(responseData, request, responseObject) {
 				});
 				responseData.getColumns = getColumns;
 			}
-			let stream = serializer.serializer.serializeStream(responseData, responseObject);
+			let stream = serializer.serializer.serializeStream(responseData, responseObject, request);
 			if (canCompress) {
 				responseObject.headers.set('Content-Encoding', 'br');
+				const uncompressedStream = stream;
 				stream = stream.pipe(
 					createBrotliCompress({
 						params: {
@@ -421,6 +471,7 @@ export function serialize(responseData, request, responseObject) {
 						},
 					})
 				);
+				if (uncompressedStream[streamStartup]) stream[streamStartup] = uncompressedStream[streamStartup];
 			}
 			return stream;
 		}
@@ -623,24 +674,146 @@ function deserializerUnknownType(contentType: ContentType): Deserialize {
 	}
 }
 
-function transformIterable(iterable, transform) {
+function errorFrameStream(iterable, transform, serializeError, eager: boolean) {
+	const transformed = transformIterable(iterable, transform, serializeError, eager);
+	const readable = Readable.from(transformed);
+	const startup: StreamStartup = transformed[streamStartup];
+	startup.cancel = () => readable.destroy();
+	readable[streamStartup] = startup;
+	return readable;
+}
+
+export function discardSerializedStream(stream) {
+	stream?.[streamStartup]?.cancel?.();
+	stream?.destroy?.();
+}
+
+export function waitForStreamStartup(stream) {
+	const startup: StreamStartup | undefined = stream?.[streamStartup];
+	if (!startup) return;
+	startup.start();
+	return startup.result.then((result) => {
+		if (result.failed) {
+			startup.abort();
+			discardSerializedStream(stream);
+			throw result.error;
+		}
+	});
+}
+
+function transformIterable(iterable, transform, serializeError, eager) {
+	let iterator;
+	let terminal = false;
+	let first = true;
+	let started = false;
+	let firstStep;
+	let startupSettled = false;
+	const startupResult = Promise.withResolvers<{ failed?: true; error?: unknown }>();
+	const errorDecision = Promise.withResolvers<boolean>();
+	let startupTimer;
+
+	const commit = () => {
+		if (startupTimer) clearImmediate(startupTimer);
+		if (!startupSettled) {
+			startupSettled = true;
+			startupResult.resolve({});
+		}
+		errorDecision.resolve(true);
+	};
+	const abort = () => {
+		if (startupTimer) clearImmediate(startupTimer);
+		errorDecision.resolve(false);
+	};
+	const handleError = async (error) => {
+		terminal = true;
+		try {
+			const returned = iterator.return?.();
+			returned?.catch?.(() => {});
+		} catch {}
+		if (!startupSettled) startupResult.resolve({ failed: true, error });
+		if (!startupSettled && !(await errorDecision.promise)) return { done: true };
+		logger.warn?.('Error serializing in stream', harperErrorForLog(error));
+		return { value: serializeError(error), done: false, [serializedStreamError]: true };
+	};
+	const transformStep = (step) => {
+		if (step?.[serializedStreamError]) return step;
+		if (terminal) return { done: true };
+		if (step.done) return step;
+		try {
+			return { value: transform(step.value), done: false };
+		} catch (error) {
+			return handleError(error);
+		}
+	};
+	const getRawNext = () => {
+		if (terminal) return { done: true };
+		let step;
+		try {
+			step = iterator.next();
+		} catch (error) {
+			return handleError(error);
+		}
+		if (step.then) return step.then(undefined, handleError);
+		return step;
+	};
+	const getNext = () => {
+		if (terminal) return { done: true };
+		let step;
+		try {
+			step = iterator.next();
+		} catch (error) {
+			return handleError(error);
+		}
+		if (step.then) return step.then(transformStep, handleError);
+		return transformStep(step);
+	};
+	const start = () => {
+		if (started) return;
+		started = true;
+		iterator = iterable[Symbol.asyncIterator] ? iterable[Symbol.asyncIterator]() : iterable[Symbol.iterator]();
+		firstStep = getRawNext();
+		Promise.resolve(firstStep).then(
+			() => {
+				if (!terminal) commit();
+			},
+			() => {}
+		);
+		// After this turn, the HTTP status can no longer wait for a first item without delaying long-lived streams.
+		startupTimer = setImmediate(commit);
+	};
+	if (eager) start();
+
 	return {
+		[streamStartup]: {
+			result: startupResult.promise,
+			abort,
+			start,
+		},
 		[Symbol.asyncIterator]() {
-			const iterator = iterable[Symbol.asyncIterator] ? iterable[Symbol.asyncIterator]() : iterable[Symbol.iterator]();
 			return {
 				next() {
-					const step = iterator.next();
-					if (step.then) {
-						// don't transform the terminal sentinel step, whose value is undefined
-						return step.then((result) => (result.done ? result : { value: transform(result.value), done: false }));
+					if (terminal) return { done: true };
+					if (first) {
+						first = false;
+						start();
+						const step = firstStep;
+						firstStep = undefined;
+						if (step.then) return step.then(transformStep);
+						return transformStep(step);
 					}
-					return step.done ? step : { value: transform(step.value), done: false };
+					return getNext();
 				},
 				return(value) {
-					return iterator.return(value);
+					terminal = true;
+					started = true;
+					if (!iterator)
+						iterator = iterable[Symbol.asyncIterator]
+							? iterable[Symbol.asyncIterator]()
+							: iterable[Symbol.iterator]?.();
+					return iterator?.return?.(value) ?? { value, done: true };
 				},
 				throw(error) {
-					return iterator.throw(error);
+					return iterator?.throw?.(error) ?? Promise.reject(error);
 				},
 			};
 		},