@warlock.js/core 5.30.0 → 5.31.0

package/esm/http/response.mjs

@@ -1,12 +1,14 @@
 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";
@@ -290,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);
@@ -382,11 +390,14 @@ var Response = class Response {
 	* @returns Stream controller with send(), write(), render(), drain() and end() methods
 	*/
 	stream(contentType = "text/plain", options = {}) {
-		this.setContentType(contentType);
-		this.header("Transfer-Encoding", "chunked");
+		validateStreamQueueOptions(options);
 		this.header("Cache-Control", "no-cache");
-		this.keepLongLivedConnectionAlive();
+		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");
@@ -396,6 +407,8 @@ var Response = class Response {
 			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();
 		raw.writeHead(this.statusCode, this.getHeaders());
 		/**
@@ -405,14 +418,22 @@ var Response = class Response {
 		*/
 		const canWrite = (action) => {
 			if (transport.disconnected) return false;
-			if (transport.closed) throw new Error(`Cannot ${action}: stream has already ended`);
+			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);
-			raw.write(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. Does not wait for the client.
 			* @param data - Data to send (string or Buffer)
@@ -427,9 +448,9 @@ var Response = class Response {
 			* stream ended or the client disconnected (stop producing).
 			*/
 			write: (data) => {
-				if (transport.closed) return Promise.resolve(false);
+				if (transport.closed || queue.ending) return Promise.resolve(false);
 				writeChunk(data);
-				return transport.waitForDrain();
+				return queue.waitForDrain();
 			},
 			/**
 			* Render a React component and send it as a chunk
@@ -442,21 +463,23 @@ var Response = class Response {
 			/**
 			* Wait until buffered output has been flushed to the client.
 			*/
-			drain: () => transport.waitForDrain(),
+			drain: () => queue.waitForDrain(),
 			/**
 			* End the stream and trigger completion events
 			*/
 			end: () => {
-				if (transport.closed) return this;
-				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);
+				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;
 			},
 			/**
@@ -474,13 +497,16 @@ var Response = class Response {
 			* Whether the transport is holding more than its high-water mark.
 			*/
 			get backpressured() {
-				return transport.backpressured;
+				return queue.backpressured;
+			},
+			get dropped() {
+				return queue.dropped;
 			},
 			/**
 			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return transport.closed;
+				return transport.closed || queue.ending;
 			}
 		};
 		return controller;
@@ -550,10 +576,14 @@ var Response = class Response {
 	* @returns SSE controller with send(), write(), drain(), comment(), and end() methods
 	*/
 	sse(options = {}) {
-		this.setContentType("text/event-stream");
+		validateStreamQueueOptions(options);
 		this.header("Cache-Control", "no-cache, no-store, must-revalidate");
-		this.keepLongLivedConnectionAlive();
+		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");
@@ -563,33 +593,45 @@ var Response = class Response {
 			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) => {
-			const safeEvent = toSingleLineSseField(event);
+		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`;
-			message += `event: ${safeEvent}\n`;
-			message += `data: ${JSON.stringify(data)}\n\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
 			});
-			raw.write(message);
+			return true;
 		};
-		const waitForDrain = () => transport.waitForDrain();
+		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 (transport.closed) return controller;
-				writeMessage(event, data, id);
+			send: (event, data, id, messageOptions) => {
+				if (transport.closed || queue.ending) return controller;
+				writeMessage(event, data, id, messageOptions);
 				return controller;
 			},
 			/**
@@ -597,9 +639,9 @@ var Response = class Response {
 			* @returns `true` once the transport can accept more, `false` if the
 			* stream ended or the client disconnected (stop producing).
 			*/
-			write: (event, data, id) => {
-				if (transport.closed) return Promise.resolve(false);
-				writeMessage(event, data, id);
+			write: (event, data, id, messageOptions) => {
+				if (transport.closed || queue.ending) return Promise.resolve(false);
+				writeMessage(event, data, id, messageOptions);
 				return waitForDrain();
 			},
 			/**
@@ -612,24 +654,27 @@ var Response = class Response {
 			* @param text - Comment text
 			*/
 			comment: (text) => {
-				if (transport.closed) return controller;
-				const lines = String(text).split(/\r\n|\r|\n/);
-				raw.write(`${lines.map((line) => `: ${line}`).join("\n")}\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 (transport.closed) return controller;
-				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);
+				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;
 			},
 			/**
@@ -656,13 +701,16 @@ var Response = class Response {
 			* Whether the transport is holding more than its high-water mark.
 			*/
 			get backpressured() {
-				return transport.backpressured;
+				return queue.backpressured;
+			},
+			get dropped() {
+				return queue.dropped;
 			},
 			/**
 			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return transport.closed;
+				return transport.closed || queue.ending;
 			}
 		};
 		return controller;
@@ -696,6 +744,23 @@ 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`
@@ -704,8 +769,21 @@ var Response = class Response {
 	* 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") return;
+		if (typeof current === "string" && current.toLowerCase() === "close") {
+			this.header("Connection", "close");
+			return;
+		}
 		this.header("Connection", "keep-alive");
 	}
 	/**
@@ -973,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";
@@ -1017,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");
@@ -1123,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