@warlock.js/core 5.29.0 → 5.31.0

package/esm/http/response.mjs

@@ -1,12 +1,15 @@
 import { LOCALE_COOKIE_NAME, LOCALE_PREFERENCE_COOKIE_NAME, resolveLocaleConfiguration } from "../config/locale-configuration.mjs";
+import { evaluateConditionalRequest } from "./conditional-request.mjs";
+import { validationFailureStatus } from "../validation/validation-failure-status.mjs";
 import { Application } from "../application/application.mjs";
 import { UnknownLocaleError } from "../errors/unknown-locale-error.mjs";
 import { StorageFile } from "../storage/storage-file.mjs";
 import "../storage/index.mjs";
 import { renderReact } from "../react/index.mjs";
-import { matchesIfNoneMatch } from "./uploads/matches-if-none-match.mjs";
 import { flushPendingCookies } from "./flush-pending-cookies.mjs";
 import { streamReactResponse } from "./stream-react-response.mjs";
+import { createBoundedStreamQueue, validateStreamQueueOptions } from "./bounded-stream-queue.mjs";
+import { createRetainedTail, createStreamTransport } from "./stream-transport.mjs";
 import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import path from "path";
@@ -16,7 +19,7 @@ import { fileExistsAsync } from "@warlock.js/fs";
 import fs from "fs";
 import mime from "mime";
 
-//#region ../core/src/http/response.ts
+//#region ../../packages/core/src/http/response.ts
 let ResponseStatus = /* @__PURE__ */ function(ResponseStatus) {
 	ResponseStatus[ResponseStatus["OK"] = 200] = "OK";
 	ResponseStatus[ResponseStatus["CREATED"] = 201] = "CREATED";
@@ -56,6 +59,14 @@ function secureCookieDefaults() {
 		secure: !Application.isDevelopment
 	};
 }
+/**
+* Make a value safe for a single-line SSE field (`event:`, `id:`): line breaks
+* would end the field and inject the rest as new fields or events, and the
+* spec makes a client ignore an `id` containing NUL. All three are removed.
+*/
+function toSingleLineSseField(value) {
+	return String(value).replace(/[\r\n\0]/g, "");
+}
 var Response = class Response {
 	constructor() {
 		this.currentStatusCode = 200;
@@ -205,8 +216,8 @@ var Response = class Response {
 			message,
 			type: level,
 			context: {
-				request: this.request,
-				response: this
+				request: this.request.toLogSnapshot(),
+				response: { statusCode: this.statusCode }
 			}
 		});
 	}
@@ -281,6 +292,12 @@ var Response = class Response {
 		this.fireSentEvents(304);
 		return reply;
 	}
+	/** Send a bare 412 (a failed `If-Match` / `If-Unmodified-Since`) and fire the lifecycle. */
+	send412() {
+		const reply = this.baseResponse.status(412).send();
+		this.fireSentEvents(412);
+		return reply;
+	}
 	/** Send a raw stream/buffer body and fire the lifecycle. */
 	sendRaw(body) {
 		const reply = this.baseResponse.send(body);
@@ -348,7 +365,7 @@ var Response = class Response {
 	* Create a streaming response for progressive/chunked data sending
 	*
 	* This method allows you to send data in chunks and control when the response ends.
-	* Perfect for Server-Sent Events (SSE), progressive rendering, or streaming large responses.
+	* Perfect for progressive rendering or streaming large responses.
 	*
 	* @example
 	* ```ts
@@ -358,68 +375,141 @@ var Response = class Response {
 	* stream.render(<MyComponent />);
 	* stream.send("</body></html>");
 	* stream.end();
+	*
+	* // Long-lived or high-volume streams: wait for the client to catch up
+	* for await (const line of output) {
+	*   if (!(await stream.write(line))) break; // client is gone
+	* }
 	* ```
 	*
+	* Written chunks are not kept: after `end()`, `response.body` holds only the
+	* last `retainChunks` chunks (none by default), so a stream that runs for
+	* hours costs the same memory as one that runs for seconds.
+	*
 	* @param contentType - The content type for the stream (default: "text/plain")
-	* @returns Stream controller with send(), render(), and end() methods
+	* @returns Stream controller with send(), write(), render(), drain() and end() methods
 	*/
-	stream(contentType = "text/plain") {
-		this.setContentType(contentType);
-		this.header("Transfer-Encoding", "chunked");
+	stream(contentType = "text/plain", options = {}) {
+		validateStreamQueueOptions(options);
 		this.header("Cache-Control", "no-cache");
-		this.header("Connection", "keep-alive");
+		this.applyStreamHeaders(options.headers);
+		this.removeHeader("Content-Length");
+		this.setContentType(contentType);
+		if (this.isHttp11()) this.header("Transfer-Encoding", "chunked");
 		this.header("X-Content-Type-Options", "nosniff");
+		this.keepLongLivedConnectionAlive();
 		Response.trigger("sending", this);
 		for (const callback of this.events.get("sending") || []) callback(this);
 		this.log("Starting stream");
-		let isEnded = false;
-		const chunks = [];
+		const raw = this.baseResponse.raw;
+		const retained = createRetainedTail(options.retainChunks);
+		const transport = createStreamTransport(raw, {
+			disconnectMessage: "The client disconnected from the stream",
+			onClientDisconnected: () => this.log("Stream client disconnected")
+		});
+		const queue = createBoundedStreamQueue(raw, transport, options);
+		let bounded = options.maxQueuedBytes !== void 0;
 		this.flushPendingCookies();
-		this.baseResponse.raw.writeHead(this.statusCode, this.getHeaders());
-		return {
+		raw.writeHead(this.statusCode, this.getHeaders());
+		/**
+		* `false` when nothing should be written: after a client disconnect the
+		* write is a silent no-op (the producer learns it through `signal`,
+		* `write()` or `ended`); after `end()` it is a programming error.
+		*/
+		const canWrite = (action) => {
+			if (transport.disconnected) return false;
+			if (transport.closed || queue.ending) throw new Error(`Cannot ${action}: stream has already ended`);
+			return true;
+		};
+		const writeChunk = (chunk) => {
+			if (bounded) {
+				if (!queue.enqueue(chunk)) return false;
+			} else raw.write(chunk);
+			retained.push(chunk);
+			return true;
+		};
+		const controller = {
+			enqueue: (data) => {
+				bounded = true;
+				if (transport.closed || queue.ending) return false;
+				return writeChunk(data);
+			},
 			/**
-			* Send a chunk of data to the client
-			* @param data - Data to send (string, Buffer, or any serializable data)
+			* Send a chunk of data to the client. Does not wait for the client.
+			* @param data - Data to send (string or Buffer)
 			*/
 			send: (data) => {
-				if (isEnded) throw new Error("Cannot send data: stream has already ended");
-				this.baseResponse.raw.write(data);
+				if (canWrite("send data")) writeChunk(data);
 				return this;
 			},
 			/**
+			* Send a chunk and wait until the client has taken it.
+			* @returns `true` once the transport can accept more, `false` if the
+			* stream ended or the client disconnected (stop producing).
+			*/
+			write: (data) => {
+				if (transport.closed || queue.ending) return Promise.resolve(false);
+				writeChunk(data);
+				return queue.waitForDrain();
+			},
+			/**
 			* Render a React component and send it as a chunk
 			* @param element - React element or component to render
 			*/
 			render: (element) => {
-				if (isEnded) throw new Error("Cannot render: stream has already ended");
-				const html = renderReact(element);
-				chunks.push(html);
-				this.baseResponse.raw.write(html);
+				if (canWrite("render")) writeChunk(renderReact(element));
 				return this;
 			},
 			/**
+			* Wait until buffered output has been flushed to the client.
+			*/
+			drain: () => queue.waitForDrain(),
+			/**
 			* End the stream and trigger completion events
 			*/
 			end: () => {
-				if (isEnded) return this;
-				isEnded = true;
-				this.currentBody = chunks;
-				this.parsedBody = chunks;
-				this.baseResponse.raw.end();
-				this.log("Stream ended");
-				Response.trigger("sent", this);
-				for (const callback of this.events.get("sent") || []) callback(this);
-				if (this.isOk) Response.trigger("success", this);
-				if (this.currentStatusCode === 201) Response.trigger("successCreate", this);
+				if (transport.closed || queue.ending) return this;
+				queue.finish(() => {
+					transport.finish();
+					this.currentBody = retained.items;
+					this.parsedBody = retained.items;
+					raw.end();
+					this.log("Stream ended");
+					Response.trigger("sent", this);
+					for (const callback of this.events.get("sent") || []) callback(this);
+					if (this.isOk) Response.trigger("success", this);
+					if (this.currentStatusCode === 201) Response.trigger("successCreate", this);
+				});
 				return this;
 			},
 			/**
-			* Check if the stream has ended
+			* Register a handler to be called when the client disconnects.
+			*/
+			onDisconnect: (handler) => {
+				transport.onDisconnect(handler);
+				return controller;
+			},
+			/**
+			* Aborted when the client disconnects (not when `end()` is called).
+			*/
+			signal: transport.signal,
+			/**
+			* Whether the transport is holding more than its high-water mark.
+			*/
+			get backpressured() {
+				return queue.backpressured;
+			},
+			get dropped() {
+				return queue.dropped;
+			},
+			/**
+			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return isEnded;
+				return transport.closed || queue.ending;
 			}
 		};
+		return controller;
 	}
 	/**
 	* Pipe a React server stream (`renderToPipeableStream`) onto this
@@ -466,6 +556,11 @@ var Response = class Response {
 	* sse.send("message", { text: "Hello!" });
 	* sse.send("notification", { type: "info", message: "Update available" }, "msg-123");
 	*
+	* // Long-lived or high-volume streams: wait for the client to catch up
+	* for await (const line of terminalOutput) {
+	*   if (!(await sse.write("output", { line }))) break; // client is gone
+	* }
+	*
 	* // Keep connection alive
 	* const keepAlive = setInterval(() => sse.comment("ping"), 30000);
 	*
@@ -474,72 +569,112 @@ var Response = class Response {
 	* sse.end();
 	* ```
 	*
-	* @returns SSE controller with send(), comment(), and end() methods
+	* Sent events are not kept: after `end()`, `response.body` holds only the
+	* last `retainEvents` events (none by default), so a stream that runs for
+	* hours costs the same memory as one that runs for seconds.
+	*
+	* @returns SSE controller with send(), write(), drain(), comment(), and end() methods
 	*/
-	sse() {
-		this.setContentType("text/event-stream");
+	sse(options = {}) {
+		validateStreamQueueOptions(options);
 		this.header("Cache-Control", "no-cache, no-store, must-revalidate");
-		this.header("Connection", "keep-alive");
+		this.applyStreamHeaders(options.headers);
+		this.removeHeader("Content-Length");
+		if (this.isHttp11()) this.header("Transfer-Encoding", "chunked");
+		this.setContentType("text/event-stream");
 		this.header("X-Accel-Buffering", "no");
+		this.keepLongLivedConnectionAlive();
 		Response.trigger("sending", this);
 		for (const callback of this.events.get("sending") || []) callback(this);
 		this.log("Starting SSE stream");
-		let isEnded = false;
-		const events = [];
-		const disconnectHandlers = [];
-		this.flushPendingCookies();
-		this.baseResponse.raw.writeHead(this.statusCode, this.getHeaders());
-		this.baseResponse.raw.on("close", () => {
-			if (!isEnded) {
-				isEnded = true;
-				this.log("SSE client disconnected");
-				for (const handler of disconnectHandlers) handler();
-			}
+		const raw = this.baseResponse.raw;
+		const retained = createRetainedTail(options.retainEvents);
+		const transport = createStreamTransport(raw, {
+			disconnectMessage: "The client disconnected from the SSE stream",
+			onClientDisconnected: () => this.log("SSE client disconnected")
 		});
+		const queue = createBoundedStreamQueue(raw, transport, options);
+		let bounded = options.maxQueuedBytes !== void 0;
+		this.flushPendingCookies();
+		raw.writeHead(this.statusCode, this.getHeaders());
+		const writeMessage = (event, data, id, messageOptions = {}) => {
+			if (messageOptions.raw && typeof data !== "string") throw new TypeError("Raw SSE data must be a string");
+			const safeEvent = event === void 0 ? void 0 : toSingleLineSseField(event);
+			const safeId = id === void 0 ? void 0 : toSingleLineSseField(id);
+			const payload = messageOptions.raw ? data : JSON.stringify(data);
+			let message = "";
+			if (safeId) message += `id: ${safeId}\n`;
+			if (safeEvent !== void 0) message += `event: ${safeEvent}\n`;
+			message += String(payload).split(/\r\n|\r|\n/).map((line) => `data: ${line}\n`).join("") + "\n";
+			if (bounded) {
+				if (!queue.enqueue(message)) return false;
+			} else raw.write(message);
+			retained.push({
+				event,
+				data,
+				id
+			});
+			return true;
+		};
+		const waitForDrain = () => queue.waitForDrain();
 		const controller = {
+			enqueue: (event, data, id, messageOptions) => {
+				bounded = true;
+				if (transport.closed || queue.ending) return false;
+				return writeMessage(event, data, id, messageOptions);
+			},
 			/**
 			* Send an SSE event
 			* @param event - Event name (e.g., "message", "chunk", "done")
 			* @param data - Event data (will be JSON stringified)
 			* @param id - Optional event ID for client-side Last-Event-ID tracking (reconnect support)
 			*/
-			send: (event, data, id) => {
-				if (isEnded) return controller;
-				let message = "";
-				if (id) message += `id: ${id}\n`;
-				message += `event: ${event}\n`;
-				message += `data: ${JSON.stringify(data)}\n\n`;
-				events.push({
-					event,
-					data,
-					id
-				});
-				this.baseResponse.raw.write(message);
+			send: (event, data, id, messageOptions) => {
+				if (transport.closed || queue.ending) return controller;
+				writeMessage(event, data, id, messageOptions);
 				return controller;
 			},
 			/**
+			* Send an SSE event and wait until the client has taken it.
+			* @returns `true` once the transport can accept more, `false` if the
+			* stream ended or the client disconnected (stop producing).
+			*/
+			write: (event, data, id, messageOptions) => {
+				if (transport.closed || queue.ending) return Promise.resolve(false);
+				writeMessage(event, data, id, messageOptions);
+				return waitForDrain();
+			},
+			/**
+			* Wait until buffered output has been flushed to the client.
+			*/
+			drain: waitForDrain,
+			/**
 			* Send a comment (keeps connection alive, invisible to client)
 			* Useful for preventing timeout on long-lived connections
 			* @param text - Comment text
 			*/
 			comment: (text) => {
-				if (isEnded) return controller;
-				this.baseResponse.raw.write(`: ${text}\n\n`);
+				if (transport.closed || queue.ending) return controller;
+				const message = `${String(text).split(/\r\n|\r|\n/).map((line) => `: ${line}`).join("\n")}\n\n`;
+				if (bounded) queue.enqueue(message);
+				else raw.write(message);
 				return controller;
 			},
 			/**
 			* End the SSE stream and trigger completion events
 			*/
 			end: () => {
-				if (isEnded) return controller;
-				isEnded = true;
-				this.currentBody = events;
-				this.parsedBody = events;
-				this.baseResponse.raw.end();
-				this.log("SSE stream ended");
-				Response.trigger("sent", this);
-				for (const callback of this.events.get("sent") || []) callback(this);
-				if (this.isOk) Response.trigger("success", this);
+				if (transport.closed || queue.ending) return controller;
+				queue.finish(() => {
+					transport.finish();
+					this.currentBody = retained.items;
+					this.parsedBody = retained.items;
+					raw.end();
+					this.log("SSE stream ended");
+					Response.trigger("sent", this);
+					for (const callback of this.events.get("sent") || []) callback(this);
+					if (this.isOk) Response.trigger("success", this);
+				});
 				return controller;
 			},
 			/**
@@ -555,14 +690,27 @@ var Response = class Response {
 			* ```
 			*/
 			onDisconnect: (handler) => {
-				disconnectHandlers.push(handler);
+				transport.onDisconnect(handler);
 				return controller;
 			},
 			/**
+			* Aborted when the client disconnects (not when `end()` is called).
+			*/
+			signal: transport.signal,
+			/**
+			* Whether the transport is holding more than its high-water mark.
+			*/
+			get backpressured() {
+				return queue.backpressured;
+			},
+			get dropped() {
+				return queue.dropped;
+			},
+			/**
 			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return isEnded;
+				return transport.closed || queue.ending;
 			}
 		};
 		return controller;
@@ -596,6 +744,48 @@ var Response = class Response {
 	getResponseTime() {
 		return this.baseResponse.elapsedTime;
 	}
+	isHttp11() {
+		const request = this.baseResponse.raw.req;
+		return request?.httpVersionMajor === 1 && request.httpVersionMinor >= 1;
+	}
+	/** Apply cache/application overrides without letting callers change framing. */
+	applyStreamHeaders(headers = {}) {
+		const protectedHeaders = new Set([
+			"content-length",
+			"transfer-encoding",
+			"content-type",
+			"connection",
+			"keep-alive",
+			"proxy-connection",
+			"upgrade"
+		]);
+		for (const [name, value] of Object.entries(headers)) if (!protectedHeaders.has(name.toLowerCase())) this.header(name, value);
+	}
+	/**
+	* Ask a long-lived response (`sse()`, `stream()`) to keep its connection
+	* open, unless a graceful shutdown already marked it `Connection: close`
+	* (see `beginHttpDrain`). The reply's own headers win over the raw ones at
+	* `writeHead`, so setting keep-alive unconditionally would undo the drain
+	* and hold the server's `close()` until the shutdown budget runs out.
+	*/
+	keepLongLivedConnectionAlive() {
+		if (!this.isHttp11()) {
+			for (const name of [
+				"connection",
+				"keep-alive",
+				"proxy-connection",
+				"upgrade",
+				"transfer-encoding"
+			]) this.removeHeader(name);
+			return;
+		}
+		const current = this.baseResponse.raw.getHeader("connection");
+		if (typeof current === "string" && current.toLowerCase() === "close") {
+			this.header("Connection", "close");
+			return;
+		}
+		this.header("Connection", "keep-alive");
+	}
 	/**
 	* Remove a specific header
 	*/
@@ -861,21 +1051,34 @@ var Response = class Response {
 		if (!/[^\x20-\x7E]/.test(name)) return `${type}; filename="${ascii}"`;
 		return `${type}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name).replace(/['()*]/g, (char) => "%" + char.charCodeAt(0).toString(16).toUpperCase())}`;
 	}
-	applyResponseOptions(options, defaultFilename) {
+	applyResponseOptions(options, defaultFilename, lastModified) {
 		if (options.contentType) this.baseResponse.type(options.contentType);
 		if (options.cacheTime) {
 			const cacheControl = options.immutable ? `public, max-age=${options.cacheTime}, immutable` : `public, max-age=${options.cacheTime}`;
 			this.header("Cache-Control", cacheControl);
 			this.header("Expires", new Date(Date.now() + options.cacheTime * 1e3).toUTCString());
 		}
-		if (options.etag) {
-			this.header("ETag", options.etag);
-			const ifNoneMatch = this.request.header("if-none-match");
-			if (ifNoneMatch && matchesIfNoneMatch(ifNoneMatch, options.etag)) {
-				this.log("Content not modified (ETag match), sending 304");
+		if (options.etag) this.header("ETag", options.etag);
+		if (options.etag || lastModified) {
+			const outcome = evaluateConditionalRequest({
+				method: this.request.method,
+				etag: options.etag,
+				lastModified,
+				ifMatch: this.request.header("if-match"),
+				ifNoneMatch: this.request.header("if-none-match"),
+				ifModifiedSince: this.request.header("if-modified-since"),
+				ifUnmodifiedSince: this.request.header("if-unmodified-since")
+			});
+			if (outcome === "not-modified") {
+				this.log("Content not modified, sending 304");
 				this.send304();
 				return true;
 			}
+			if (outcome === "precondition-failed") {
+				this.log("Precondition failed, sending 412");
+				this.send412();
+				return true;
+			}
 		}
 		if (options.inline !== void 0 || options.filename) {
 			const disposition = options.inline ? "inline" : "attachment";
@@ -905,20 +1108,7 @@ var Response = class Response {
 				...opts,
 				etag,
 				contentType
-			}, defaultFilename)) return this.baseResponse;
-			const ifNoneMatch = this.request.header("if-none-match");
-			const ifModifiedSince = this.request.header("if-modified-since");
-			if (ifNoneMatch && matchesIfNoneMatch(ifNoneMatch, etag)) {
-				this.log("File not modified (ETag match), sending 304");
-				return this.send304();
-			}
-			if (ifModifiedSince && !ifNoneMatch) {
-				const modifiedSinceDate = new Date(ifModifiedSince);
-				if (Math.floor(lastModified.getTime() / 1e3) <= Math.floor(modifiedSinceDate.getTime() / 1e3)) {
-					this.log("File not modified (Last-Modified check), sending 304");
-					return this.send304();
-				}
-			}
+			}, defaultFilename, lastModified)) return this.baseResponse;
 			const stream = fs.createReadStream(filePath);
 			stream.on("error", (error) => {
 				this.log(`Error reading file: ${error.message}`, "error");
@@ -1011,17 +1201,27 @@ var Response = class Response {
 		return mime.getType(filePath) || "application/octet-stream";
 	}
 	/**
-	* Mark the response as failed
-	*/
-	failedSchema(result) {
-		const { errors, inputKey, inputError, status } = {
+	* Answer a failed schema validation.
+	*
+	* Uses the global `validation.response.body(result, route)` hook when it is
+	* configured and returns a body; otherwise the framework body,
+	* `{ [errors]: [{ [inputKey], [inputError] }] }`. The status is
+	* `validation.response.status` (422 by default) either way.
+	*/
+	async failedSchema(result) {
+		const settings = config.get("validation.response", {});
+		const { errors, inputKey, inputError } = {
 			errors: "errors",
 			inputKey: "input",
 			inputError: "error",
-			status: 422,
-			...config.get("validation.response", {})
+			...settings
 		};
+		const status = validationFailureStatus();
 		log.error("request", "validation", `${this.request.id} - Validation failed`);
+		if (typeof settings.body === "function") {
+			const body = await settings.body(result, this.request.route);
+			if (body !== void 0) return this.send(body, status);
+		}
 		return this.send({ [errors]: result.errors.map((error) => ({
 			[inputKey]: error.input,
 			[inputError]: error.error
@@ -1030,5 +1230,5 @@ var Response = class Response {
 };
 
 //#endregion
-export { Response, ResponseStatus };
+export { Response, ResponseStatus, toSingleLineSseField };
 //# sourceMappingURL=response.mjs.map