@warlock.js/core 5.28.0 → 5.30.0

package/esm/http/response.mjs

@@ -7,6 +7,7 @@ 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 { createRetainedTail, createStreamTransport } from "./stream-transport.mjs";
 import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import path from "path";
@@ -16,7 +17,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 +57,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 +214,8 @@ var Response = class Response {
 			message,
 			type: level,
 			context: {
-				request: this.request,
-				response: this
+				request: this.request.toLogSnapshot(),
+				response: { statusCode: this.statusCode }
 			}
 		});
 	}
@@ -348,7 +357,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,54 +367,91 @@ 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") {
+	stream(contentType = "text/plain", options = {}) {
 		this.setContentType(contentType);
 		this.header("Transfer-Encoding", "chunked");
 		this.header("Cache-Control", "no-cache");
-		this.header("Connection", "keep-alive");
+		this.keepLongLivedConnectionAlive();
 		this.header("X-Content-Type-Options", "nosniff");
 		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")
+		});
 		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) throw new Error(`Cannot ${action}: stream has already ended`);
+			return true;
+		};
+		const writeChunk = (chunk) => {
+			retained.push(chunk);
+			raw.write(chunk);
+		};
+		const controller = {
 			/**
-			* 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) return Promise.resolve(false);
+				writeChunk(data);
+				return transport.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: () => transport.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();
+				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);
@@ -414,12 +460,30 @@ var Response = class Response {
 				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 transport.backpressured;
+			},
+			/**
+			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return isEnded;
+				return transport.closed;
 			}
 		};
+		return controller;
 	}
 	/**
 	* Pipe a React server stream (`renderToPipeableStream`) onto this
@@ -466,6 +530,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,28 +543,43 @@ 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() {
+	sse(options = {}) {
 		this.setContentType("text/event-stream");
 		this.header("Cache-Control", "no-cache, no-store, must-revalidate");
-		this.header("Connection", "keep-alive");
+		this.keepLongLivedConnectionAlive();
 		this.header("X-Accel-Buffering", "no");
 		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")
 		});
+		this.flushPendingCookies();
+		raw.writeHead(this.statusCode, this.getHeaders());
+		const writeMessage = (event, data, id) => {
+			const safeEvent = toSingleLineSseField(event);
+			const safeId = id === void 0 ? void 0 : toSingleLineSseField(id);
+			let message = "";
+			if (safeId) message += `id: ${safeId}\n`;
+			message += `event: ${safeEvent}\n`;
+			message += `data: ${JSON.stringify(data)}\n\n`;
+			retained.push({
+				event,
+				data,
+				id
+			});
+			raw.write(message);
+		};
+		const waitForDrain = () => transport.waitForDrain();
 		const controller = {
 			/**
 			* Send an SSE event
@@ -504,38 +588,44 @@ var Response = class Response {
 			* @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);
+				if (transport.closed) return controller;
+				writeMessage(event, data, id);
 				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) => {
+				if (transport.closed) return Promise.resolve(false);
+				writeMessage(event, data, id);
+				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) return controller;
+				const lines = String(text).split(/\r\n|\r|\n/);
+				raw.write(`${lines.map((line) => `: ${line}`).join("\n")}\n\n`);
 				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();
+				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);
@@ -555,14 +645,24 @@ 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 transport.backpressured;
+			},
+			/**
 			* Check if the stream has ended (either via end() or client disconnect)
 			*/
 			get ended() {
-				return isEnded;
+				return transport.closed;
 			}
 		};
 		return controller;
@@ -597,6 +697,18 @@ var Response = class Response {
 		return this.baseResponse.elapsedTime;
 	}
 	/**
+	* 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() {
+		const current = this.baseResponse.raw.getHeader("connection");
+		if (typeof current === "string" && current.toLowerCase() === "close") return;
+		this.header("Connection", "keep-alive");
+	}
+	/**
 	* Remove a specific header
 	*/
 	removeHeader(key) {
@@ -1030,5 +1142,5 @@ var Response = class Response {
 };
 
 //#endregion
-export { Response, ResponseStatus };
+export { Response, ResponseStatus, toSingleLineSseField };
 //# sourceMappingURL=response.mjs.map