@wooksjs/event-http 0.7.26 → 0.7.27

package/dist/index.cjs

@@ -36,6 +36,7 @@ let http = require("http");
 http = __toESM(http);
 let stream = require("stream");
 let wooks = require("wooks");
+let crypto = require("crypto");
 let net = require("net");
 
 //#region packages/event-http/src/http-kind.ts
@@ -96,18 +97,22 @@ const useCookies = (0, _wooksjs_event_core.defineWook)((ctx) => ({
 }));
 
 //#endregion
-//#region packages/event-http/src/composables/header-accept.ts
+//#region packages/event-http/src/utils/accept.ts
+/** Short Accept names mapped to their MIME types. */
 const ACCEPT_TYPE_MAP = {
 	json: "application/json",
 	html: "text/html",
 	xml: "application/xml",
 	text: "text/plain"
 };
-const acceptsMime = (0, _wooksjs_event_core.cachedBy)((type, ctx) => {
-	const accept = ctx.get(httpKind.keys.req).headers.accept;
-	const mime = ACCEPT_TYPE_MAP[type] || type;
-	return !!(accept && (accept === "*/*" || accept.includes(mime)));
-});
+/** Whether an `Accept` header value accepts `type` (a short name from {@link ACCEPT_TYPE_MAP} or a MIME type). */
+function acceptHeaderHas(accept, type) {
+	return !!(accept && (accept === "*/*" || accept.includes(ACCEPT_TYPE_MAP[type] || type)));
+}
+
+//#endregion
+//#region packages/event-http/src/composables/header-accept.ts
+const acceptsMime = (0, _wooksjs_event_core.cachedBy)((type, ctx) => acceptHeaderHas(ctx.get(httpKind.keys.req).headers.accept, type));
 /** Provides helpers to check the request's Accept header for supported MIME types. */
 const useAccept = (0, _wooksjs_event_core.defineWook)((ctx) => {
 	return {
@@ -167,6 +172,19 @@ const useAuthorization = (0, _wooksjs_event_core.defineWook)((ctx) => {
 	};
 });
 
+//#endregion
+//#region packages/event-http/src/composables/headers.ts
+/**
+* Returns the incoming request headers.
+* @example
+* ```ts
+* const { host, authorization } = useHeaders()
+* ```
+*/
+function useHeaders(ctx) {
+	return (ctx ?? (0, _wooksjs_event_core.current)()).get(httpKind.keys.req).headers;
+}
+
 //#endregion
 //#region packages/event-http/src/compressor/body-compressor.ts
 const compressors = { identity: {
@@ -416,18 +434,72 @@ const DEFAULT_LIMITS = {
 	maxRatio: 100,
 	readTimeoutMs: 1e4
 };
+const NO_ENCODINGS = Object.freeze([]);
 const contentEncodingsSlot = (0, _wooksjs_event_core.cached)((ctx) => {
-	return (ctx.get(httpKind.keys.req).headers["content-encoding"] || "").split(",").map((p) => p.trim()).filter((p) => !!p);
+	const contentEncoding = ctx.get(httpKind.keys.req).headers["content-encoding"];
+	if (!contentEncoding) return NO_ENCODINGS;
+	return contentEncoding.split(",").map((p) => p.trim()).filter((p) => !!p);
 });
 const isCompressedSlot = (0, _wooksjs_event_core.cached)((ctx) => {
-	const parts = ctx.get(contentEncodingsSlot);
-	for (const p of parts) if ([
-		"deflate",
-		"gzip",
-		"br"
-	].includes(p)) return true;
+	for (const p of ctx.get(contentEncodingsSlot)) if (p === "deflate" || p === "gzip" || p === "br") return true;
 	return false;
 });
+/**
+* Reads the whole request body with plain stream events (one listener set, one timer).
+* Raw bytes are checked against `upfrontLimit` first, then against `maxInflated`
+* (the same order as the streaming path). A stall longer than `timeoutMs` destroys the
+* request; a premature close or stream error becomes 408. The request is destroyed
+* once reading settles, as async iteration did.
+*/
+function readRawBody(req, upfrontLimit, maxInflated, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let bytes = 0;
+		if (req.readableEnded) {
+			req.destroy();
+			resolve(buffer.Buffer.alloc(0));
+			return;
+		}
+		if (req.destroyed) {
+			reject(new HttpError(408, "Request body timeout"));
+			return;
+		}
+		let done = false;
+		const timer = timeoutMs === 0 ? null : setTimeout(() => req.destroy(), timeoutMs);
+		const finish = (error) => {
+			if (done) return;
+			done = true;
+			if (timer) clearTimeout(timer);
+			req.off("data", onData);
+			req.off("end", onEnd);
+			req.off("error", onAbort);
+			req.off("close", onAbort);
+			req.destroy();
+			if (error) reject(error);
+			else resolve(chunks.length === 1 ? chunks[0] : buffer.Buffer.concat(chunks, bytes));
+		};
+		const onData = (chunk) => {
+			bytes += chunk.length;
+			if (bytes > upfrontLimit) {
+				finish(new HttpError(413, "Payload Too Large"));
+				return;
+			}
+			if (bytes > maxInflated) {
+				finish(new HttpError(413, "Inflated body too large"));
+				return;
+			}
+			timer?.refresh();
+			chunks.push(chunk);
+		};
+		const onEnd = () => finish();
+		const onAbort = () => finish(new HttpError(408, "Request body timeout"));
+		req.on("data", onData);
+		req.on("end", onEnd);
+		req.on("error", onAbort);
+		req.on("close", onAbort);
+		req.resume();
+	});
+}
 /** @internal Exported for test pre-seeding — use {@link seedRawBody} instead. */
 const rawBodySlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
 	const req = ctx.get(httpKind.keys.req);
@@ -443,6 +515,14 @@ const rawBodySlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
 	const upfrontLimit = isZip ? maxCompressed : maxInflated;
 	if (cl && cl > upfrontLimit) throw new HttpError(413, "Payload Too Large");
 	for (const enc of encs) if (!compressors[enc]) throw new HttpError(415, `Unsupported Content-Encoding "${enc}"`);
+	if (!streamable) {
+		const raw = await readRawBody(req, upfrontLimit, maxInflated, timeoutMs);
+		if (!isZip) return raw;
+		const body = await uncompressBody(encs, raw);
+		if (body.byteLength > maxInflated) throw new HttpError(413, "Inflated body too large");
+		if (raw.byteLength > 0 && body.byteLength / raw.byteLength > maxRatio) throw new HttpError(413, "Compression ratio too high");
+		return body;
+	}
 	let timer = null;
 	function resetTimer() {
 		if (timeoutMs === 0) return;
@@ -475,8 +555,7 @@ const rawBodySlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
 			clearTimer();
 		}
 	}
-	let stream = limitedCompressed();
-	if (streamable) stream = await uncompressBodyStream(encs, stream);
+	const stream = await uncompressBodyStream(encs, limitedCompressed());
 	const chunks = [];
 	let inflatedBytes = 0;
 	try {
@@ -489,14 +568,8 @@ const rawBodySlot = (0, _wooksjs_event_core.cached)(async (ctx) => {
 		if (error instanceof HttpError) throw error;
 		throw new HttpError(408, "Request body timeout");
 	}
-	let body = buffer.Buffer.concat(chunks);
-	if (!streamable && isZip) {
-		body = await uncompressBody(encs, body);
-		inflatedBytes = body.byteLength;
-		if (inflatedBytes > maxInflated) throw new HttpError(413, "Inflated body too large");
-	}
-	if (isZip && rawBytes > 0 && inflatedBytes / rawBytes > maxRatio) throw new HttpError(413, "Compression ratio too high");
-	return body;
+	if (rawBytes > 0 && inflatedBytes / rawBytes > maxRatio) throw new HttpError(413, "Compression ratio too high");
+	return buffer.Buffer.concat(chunks);
 });
 const forwardedIpSlot = (0, _wooksjs_event_core.cached)((ctx) => {
 	const req = ctx.get(httpKind.keys.req);
@@ -592,19 +665,6 @@ function seedRawBody(ctx, raw) {
 	if (ctx.parent) ctx.getOwn(useRequest._slot);
 }
 
-//#endregion
-//#region packages/event-http/src/composables/headers.ts
-/**
-* Returns the incoming request headers.
-* @example
-* ```ts
-* const { host, authorization } = useHeaders()
-* ```
-*/
-function useHeaders(ctx) {
-	return useRequest(ctx).headers;
-}
-
 //#endregion
 //#region packages/event-http/src/composables/response.ts
 /**
@@ -763,6 +823,70 @@ const cookieAttrFunc = {
 	sameSite: (v) => v ? `SameSite=${typeof v === "string" ? v : "Strict"}` : ""
 };
 
+//#endregion
+//#region packages/event-http/src/response/prerender.ts
+const registry = /* @__PURE__ */ new WeakMap();
+function weakEtag(json) {
+	return `W/"${(0, crypto.createHash)("sha256").update(json).digest("base64url").slice(0, 22)}"`;
+}
+/**
+* Serializes `obj` to JSON once and remembers the string by object identity. Whenever a handler
+* (or an interceptor) responds with that same object, the response reuses the stored JSON instead
+* of calling `JSON.stringify` again. Use it for large, long-lived response objects that many
+* requests return as is — e.g. a schema or metadata envelope built once and cached.
+*
+* With `{ etag: true }` a weak `ETag` is derived from the serialized bytes; a `GET`/`HEAD`
+* that responds `200` with the object sets the `ETag` header and answers a matching
+* `If-None-Match` with `304 Not Modified` (no body; other headers such as `Cache-Control`
+* and `Vary` are kept). Error responses never become `304`. An `ETag` header set explicitly
+* on the response wins and disables the `304` handling for that response.
+*
+* **Contract: never mutate a registered object (or anything it references).** The stored JSON
+* is not refreshed, so a mutation would keep serving the old bytes. Build a new object instead —
+* freezing registered objects (`Object.freeze`, deeply) in development makes violations throw.
+*
+* Calling it again for the same object is a no-op (it adds the `ETag` if it was not requested
+* the first time). Entries are held weakly and disappear with the object.
+*
+* @param obj - A JSON-serializable object or array
+* @param options - `{ etag: true }` to also compute a weak ETag
+* @returns The same `obj`, so it can wrap a return value
+*
+* @example
+* ```ts
+* const envelope = prerenderJson(Object.freeze(buildMeta()), { etag: true })
+* app.get('/meta', () => {
+*   useResponse().setHeader('cache-control', 'private, no-cache')
+*   return envelope // sent without re-serializing; 304 on a matching If-None-Match
+* })
+* ```
+*/
+function prerenderJson(obj, options) {
+	let entry = registry.get(obj);
+	if (!entry) {
+		const json = JSON.stringify(obj);
+		if (typeof json !== "string") throw new TypeError("prerenderJson: value does not serialize to JSON");
+		entry = { json };
+		registry.set(obj, entry);
+	}
+	if (options?.etag && !entry.etag) entry.etag = weakEtag(entry.json);
+	return obj;
+}
+/** @internal Returns the pre-serialized JSON (and weak ETag) registered for `obj`, if any. */
+function getPrerenderedJson(obj) {
+	return registry.get(obj);
+}
+/** @internal Weak comparison of `etag` against an `If-None-Match` header value. */
+function ifNoneMatchHas(header, etag) {
+	if (!header) return false;
+	const opaque = etag.startsWith("W/") ? etag.slice(2) : etag;
+	for (const part of header.split(",")) {
+		const tag = part.trim();
+		if (tag === "*" || (tag.startsWith("W/") ? tag.slice(2) : tag) === opaque) return true;
+	}
+	return false;
+}
+
 //#endregion
 //#region packages/event-http/src/response/http-response.ts
 const hasFetchResponse = typeof globalThis.Response === "function";
@@ -801,8 +925,6 @@ var HttpResponse = class {
 		this._status = 0;
 		this._body = void 0;
 		this._headers = {};
-		this._cookies = {};
-		this._rawCookies = [];
 		this._hasCookies = false;
 		this._responded = false;
 		if (defaultHeaders) for (const key in defaultHeaders) this._headers[key] = defaultHeaders[key];
@@ -870,7 +992,7 @@ var HttpResponse = class {
 	}
 	/** Sets an outgoing `Set-Cookie` header with optional attributes (chainable). */
 	setCookie(name, value, attrs) {
-		this._cookies[name] = {
+		(this._cookies ??= {})[name] = {
 			value,
 			attrs: attrs || {}
 		};
@@ -879,23 +1001,23 @@ var HttpResponse = class {
 	}
 	/** Returns a previously set cookie's data, or `undefined` if not set. */
 	getCookie(name) {
-		return this._cookies[name];
+		return this._cookies?.[name];
 	}
 	/** Removes a cookie from the outgoing set list (chainable). */
 	removeCookie(name) {
-		delete this._cookies[name];
+		if (this._cookies) delete this._cookies[name];
 		return this;
 	}
 	/** Removes all outgoing cookies (chainable). */
 	clearCookies() {
-		this._cookies = {};
-		this._rawCookies = [];
+		this._cookies = void 0;
+		this._rawCookies = void 0;
 		this._hasCookies = false;
 		return this;
 	}
 	/** Appends a raw `Set-Cookie` header string (chainable). Use when you need full control over the cookie format. */
 	setCookieRaw(rawValue) {
-		this._rawCookies.push(rawValue);
+		(this._rawCookies ??= []).push(rawValue);
 		this._hasCookies = true;
 		return this;
 	}
@@ -910,8 +1032,10 @@ var HttpResponse = class {
 	*/
 	getSetCookieStrings() {
 		const rendered = [];
-		for (const [name, data] of Object.entries(this._cookies)) if (data) rendered.push(renderCookie(name, data));
-		rendered.push(...this._rawCookies);
+		if (this._cookies) {
+			for (const [name, data] of Object.entries(this._cookies)) if (data) rendered.push(renderCookie(name, data));
+		}
+		if (this._rawCookies) rendered.push(...this._rawCookies);
 		return rendered;
 	}
 	/** Sets the `Cache-Control` header from a directive object (chainable). */
@@ -973,6 +1097,10 @@ var HttpResponse = class {
 		}
 		const rendered = this.renderBody();
 		this.autoStatus(!!rendered);
+		if (this.applyPrerenderedEtag()) return new globalThis.Response(null, {
+			status: this._status,
+			headers: this._buildWebHeaders()
+		});
 		if (rendered) {
 			const contentLength = typeof rendered === "string" ? Buffer.byteLength(rendered) : rendered.byteLength;
 			this._headers["content-length"] = contentLength.toString();
@@ -1021,6 +1149,11 @@ var HttpResponse = class {
 		if (body instanceof Uint8Array) return body;
 		if (typeof body === "object") {
 			if (!this._headers["content-type"]) this._headers["content-type"] = "application/json";
+			const prerendered = getPrerenderedJson(body);
+			if (prerendered) {
+				this._prerenderedEtag = prerendered.etag;
+				return prerendered.json;
+			}
 			return JSON.stringify(body);
 		}
 		throw new Error(`Unsupported body format "${typeof body}"`);
@@ -1072,6 +1205,31 @@ var HttpResponse = class {
 		}
 		this._hasCookies = false;
 	}
+	/**
+	* For a body registered with `prerenderJson(obj, { etag: true })`: sets the `ETag` header on a
+	* GET/HEAD 2xx response (unless one was set explicitly) and turns a `200` whose `If-None-Match`
+	* matches into a bodiless `304`. Returns `true` when the response became `304`.
+	* Other methods get no ETag (a validator on e.g. a PUT response would describe the stored resource).
+	*/
+	applyPrerenderedEtag() {
+		const etag = this._prerenderedEtag;
+		if (!etag) return false;
+		this._prerenderedEtag = void 0;
+		const method = this._req.method;
+		if (method !== "GET" && method !== "HEAD" || this._status < 200 || this._status > 299 || this.hasHeaderIgnoreCase("etag")) return false;
+		this._headers.etag = etag;
+		if (this._status !== EHttpStatusCode.OK || !ifNoneMatchHas(this._req.headers["if-none-match"], etag)) return false;
+		this._status = EHttpStatusCode.NotModified;
+		for (const key in this._headers) {
+			const lower = key.toLowerCase();
+			if (lower === "content-type" || lower === "content-length") delete this._headers[key];
+		}
+		return true;
+	}
+	hasHeaderIgnoreCase(name) {
+		for (const key in this._headers) if (key.toLowerCase() === name) return true;
+		return false;
+	}
 	autoStatus(hasBody) {
 		if (this._status) return;
 		if (!hasBody) {
@@ -1119,6 +1277,10 @@ var HttpResponse = class {
 	sendRegular(method) {
 		const renderedBody = this.renderBody();
 		this.autoStatus(!!renderedBody);
+		if (this.applyPrerenderedEtag()) {
+			this._res.writeHead(this._status, this._headers).end();
+			return;
+		}
 		const contentLength = typeof renderedBody === "string" ? Buffer.byteLength(renderedBody) : renderedBody.byteLength;
 		this._headers["content-length"] = contentLength.toString();
 		this._res.writeHead(this._status, this._headers).end(method === "HEAD" ? "" : renderedBody);
@@ -1497,7 +1659,7 @@ function escapeHtml(value) {
 //#endregion
 //#region packages/event-http/src/response/wooks-http-response.ts
 let framework = {
-	version: "0.7.26",
+	version: "0.7.27",
 	poweredBy: "wooksjs",
 	link: "https://wooks.moost.org/",
 	image: "https://wooks.moost.org/wooks-full-logo.svg"
@@ -1521,7 +1683,8 @@ var WooksHttpResponse = class extends HttpResponse {
 	}
 	renderError(data, ctx) {
 		this._status = data.statusCode || 500;
-		const { has } = useAccept(ctx);
+		const accept = ctx.get(httpKind.keys.req).headers.accept;
+		const has = (type) => acceptHeaderHas(accept, type);
 		if (has("json")) {
 			this._headers["content-type"] = "application/json";
 			this._body = JSON.stringify(data);
@@ -1817,33 +1980,19 @@ var WooksHttp = class extends wooks.WooksAdapterBase {
 		}
 	}
 	async processAsyncResult(promise, handlers, startIndex, ctx, response) {
-		try {
-			const result = await promise;
-			await this.respond(result, response, ctx);
+		for (let i = startIndex; i < handlers.length; i++) try {
+			const result = await (i === startIndex ? promise : handlers[i]());
+			const sent = this.respond(result, response, ctx);
+			if (sent) await sent;
 			return result;
 		} catch (error) {
-			const isLastHandler = startIndex === handlers.length - 1;
 			if (!(error instanceof HttpError)) this.logger.error(`Uncaught route handler exception: ${ctx.get(httpKind.keys.req)?.url || ""}`, error);
-			if (isLastHandler) {
-				await this.respond(error, response, ctx);
+			if (i === handlers.length - 1) {
+				const sent = this.respond(error, response, ctx);
+				if (sent) await sent;
 				return error;
 			}
 		}
-		for (let i = startIndex + 1; i < handlers.length; i++) {
-			const handler = handlers[i];
-			const isLastHandler = i === handlers.length - 1;
-			try {
-				const result = await handler();
-				await this.respond(result, response, ctx);
-				return result;
-			} catch (error) {
-				if (!(error instanceof HttpError)) this.logger.error(`Uncaught route handler exception: ${ctx.get(httpKind.keys.req)?.url || ""}`, error);
-				if (isLastHandler) {
-					await this.respond(error, response, ctx);
-					return error;
-				}
-			}
-		}
 	}
 	/**
 	* Programmatic route invocation using the Web Standard fetch API.
@@ -2129,6 +2278,7 @@ exports.createHttpContext = createHttpContext;
 exports.httpKind = httpKind;
 exports.httpStatusCodes = httpStatusCodes;
 exports.prepareTestHttpContext = prepareTestHttpContext;
+exports.prerenderJson = prerenderJson;
 exports.rawBodySlot = rawBodySlot;
 exports.recordToWebHeaders = recordToWebHeaders;
 exports.renderCacheControl = renderCacheControl;

package/dist/index.d.ts

@@ -80,7 +80,7 @@ declare const rawBodySlot: _wooksjs_event_core.Cached<Promise<Buffer<ArrayBuffer
  * ```
  */
 declare const useRequest: _wooksjs_event_core.WookComposable<{
-    raw: http.IncomingMessage;
+    raw: IncomingMessage;
     url: string | undefined;
     method: string | undefined;
     headers: http.IncomingHttpHeaders;
@@ -375,10 +375,14 @@ declare class HttpResponse {
     protected _status: EHttpStatusCode;
     protected _body: unknown;
     protected _headers: Record<string, string | string[]>;
-    protected _cookies: Record<string, TSetCookieData>;
-    protected _rawCookies: string[];
+    /** Outgoing named cookies — allocated on the first `setCookie()`. */
+    protected _cookies?: Record<string, TSetCookieData>;
+    /** Outgoing raw `Set-Cookie` strings — allocated on the first `setCookieRaw()`. */
+    protected _rawCookies?: string[];
     protected _hasCookies: boolean;
     protected _responded: boolean;
+    /** Weak ETag of the prerendered body picked by the last `renderBody()` (see `prerenderJson`). */
+    private _prerenderedEtag?;
     /** The HTTP status code. If not set, it is inferred automatically when `send()` is called. */
     get status(): EHttpStatusCode;
     set status(value: EHttpStatusCode);
@@ -468,6 +472,14 @@ declare class HttpResponse {
      */
     send(): void | Promise<void>;
     private finalizeCookies;
+    /**
+     * For a body registered with `prerenderJson(obj, { etag: true })`: sets the `ETag` header on a
+     * GET/HEAD 2xx response (unless one was set explicitly) and turns a `200` whose `If-None-Match`
+     * matches into a bodiless `304`. Returns `true` when the response became `304`.
+     * Other methods get no ETag (a validator on e.g. a PUT response would describe the stored resource).
+     */
+    private applyPrerenderedEtag;
+    private hasHeaderIgnoreCase;
     private autoStatus;
     private sendStream;
     /**
@@ -729,6 +741,49 @@ declare class WooksHttp extends WooksAdapterBase {
  */
 declare function createHttpApp(opts?: TWooksHttpOptions, wooks?: Wooks | WooksAdapterBase): WooksHttp;
 
+/** Options for {@link prerenderJson}. */
+interface TPrerenderJsonOptions {
+    /**
+     * Also compute a weak `ETag` from the serialized bytes. Responses that send the object then
+     * carry the `ETag` header and answer a matching `If-None-Match` (GET/HEAD, status 200) with
+     * `304 Not Modified`.
+     */
+    etag?: boolean;
+}
+/**
+ * Serializes `obj` to JSON once and remembers the string by object identity. Whenever a handler
+ * (or an interceptor) responds with that same object, the response reuses the stored JSON instead
+ * of calling `JSON.stringify` again. Use it for large, long-lived response objects that many
+ * requests return as is — e.g. a schema or metadata envelope built once and cached.
+ *
+ * With `{ etag: true }` a weak `ETag` is derived from the serialized bytes; a `GET`/`HEAD`
+ * that responds `200` with the object sets the `ETag` header and answers a matching
+ * `If-None-Match` with `304 Not Modified` (no body; other headers such as `Cache-Control`
+ * and `Vary` are kept). Error responses never become `304`. An `ETag` header set explicitly
+ * on the response wins and disables the `304` handling for that response.
+ *
+ * **Contract: never mutate a registered object (or anything it references).** The stored JSON
+ * is not refreshed, so a mutation would keep serving the old bytes. Build a new object instead —
+ * freezing registered objects (`Object.freeze`, deeply) in development makes violations throw.
+ *
+ * Calling it again for the same object is a no-op (it adds the `ETag` if it was not requested
+ * the first time). Entries are held weakly and disappear with the object.
+ *
+ * @param obj - A JSON-serializable object or array
+ * @param options - `{ etag: true }` to also compute a weak ETag
+ * @returns The same `obj`, so it can wrap a return value
+ *
+ * @example
+ * ```ts
+ * const envelope = prerenderJson(Object.freeze(buildMeta()), { etag: true })
+ * app.get('/meta', () => {
+ *   useResponse().setHeader('cache-control', 'private, no-cache')
+ *   return envelope // sent without re-serializing; 304 on a matching If-None-Match
+ * })
+ * ```
+ */
+declare function prerenderJson<T extends object>(obj: T, options?: TPrerenderJsonOptions): T;
+
 /**
  * Configuration for `securityHeaders()`. Each option accepts a `string` (override value),
  * `false` (disable), or `undefined` (use default). `strictTransportSecurity` has no default (opt-in only).
@@ -793,5 +848,5 @@ interface TTestHttpContext {
  */
 declare function prepareTestHttpContext(options: TTestHttpContext): <T>(cb: (...a: any[]) => T) => T;
 
-export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useUrlParams };
-export type { KnownAcceptType, KnownAuthType, SecurityHeadersOptions, TCacheControl, TCookieAttributes, TCookieAttributesInput, THttpEventData, TRequestLimits, TSetCookieData, TTestHttpContext, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions };
+export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, prerenderJson, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useUrlParams };
+export type { KnownAcceptType, KnownAuthType, SecurityHeadersOptions, TCacheControl, TCookieAttributes, TCookieAttributesInput, THttpEventData, TPrerenderJsonOptions, TRequestLimits, TSetCookieData, TTestHttpContext, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions };

package/dist/index.mjs

@@ -7,6 +7,7 @@ import { URLSearchParams } from "url";
 import http, { IncomingMessage, ServerResponse } from "http";
 import { Duplex, Readable as Readable$1, pipeline as pipeline$1 } from "stream";
 import { WooksAdapterBase } from "wooks";
+import { createHash } from "crypto";
 import { Socket } from "net";
 
 //#region packages/event-http/src/http-kind.ts
@@ -67,18 +68,22 @@ const useCookies = defineWook((ctx) => ({
 }));
 
 //#endregion
-//#region packages/event-http/src/composables/header-accept.ts
+//#region packages/event-http/src/utils/accept.ts
+/** Short Accept names mapped to their MIME types. */
 const ACCEPT_TYPE_MAP = {
 	json: "application/json",
 	html: "text/html",
 	xml: "application/xml",
 	text: "text/plain"
 };
-const acceptsMime = cachedBy((type, ctx) => {
-	const accept = ctx.get(httpKind.keys.req).headers.accept;
-	const mime = ACCEPT_TYPE_MAP[type] || type;
-	return !!(accept && (accept === "*/*" || accept.includes(mime)));
-});
+/** Whether an `Accept` header value accepts `type` (a short name from {@link ACCEPT_TYPE_MAP} or a MIME type). */
+function acceptHeaderHas(accept, type) {
+	return !!(accept && (accept === "*/*" || accept.includes(ACCEPT_TYPE_MAP[type] || type)));
+}
+
+//#endregion
+//#region packages/event-http/src/composables/header-accept.ts
+const acceptsMime = cachedBy((type, ctx) => acceptHeaderHas(ctx.get(httpKind.keys.req).headers.accept, type));
 /** Provides helpers to check the request's Accept header for supported MIME types. */
 const useAccept = defineWook((ctx) => {
 	return {
@@ -138,6 +143,19 @@ const useAuthorization = defineWook((ctx) => {
 	};
 });
 
+//#endregion
+//#region packages/event-http/src/composables/headers.ts
+/**
+* Returns the incoming request headers.
+* @example
+* ```ts
+* const { host, authorization } = useHeaders()
+* ```
+*/
+function useHeaders(ctx) {
+	return (ctx ?? current()).get(httpKind.keys.req).headers;
+}
+
 //#endregion
 //#region packages/event-http/src/compressor/body-compressor.ts
 const compressors = { identity: {
@@ -387,18 +405,72 @@ const DEFAULT_LIMITS = {
 	maxRatio: 100,
 	readTimeoutMs: 1e4
 };
+const NO_ENCODINGS = Object.freeze([]);
 const contentEncodingsSlot = cached((ctx) => {
-	return (ctx.get(httpKind.keys.req).headers["content-encoding"] || "").split(",").map((p) => p.trim()).filter((p) => !!p);
+	const contentEncoding = ctx.get(httpKind.keys.req).headers["content-encoding"];
+	if (!contentEncoding) return NO_ENCODINGS;
+	return contentEncoding.split(",").map((p) => p.trim()).filter((p) => !!p);
 });
 const isCompressedSlot = cached((ctx) => {
-	const parts = ctx.get(contentEncodingsSlot);
-	for (const p of parts) if ([
-		"deflate",
-		"gzip",
-		"br"
-	].includes(p)) return true;
+	for (const p of ctx.get(contentEncodingsSlot)) if (p === "deflate" || p === "gzip" || p === "br") return true;
 	return false;
 });
+/**
+* Reads the whole request body with plain stream events (one listener set, one timer).
+* Raw bytes are checked against `upfrontLimit` first, then against `maxInflated`
+* (the same order as the streaming path). A stall longer than `timeoutMs` destroys the
+* request; a premature close or stream error becomes 408. The request is destroyed
+* once reading settles, as async iteration did.
+*/
+function readRawBody(req, upfrontLimit, maxInflated, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let bytes = 0;
+		if (req.readableEnded) {
+			req.destroy();
+			resolve(Buffer$1.alloc(0));
+			return;
+		}
+		if (req.destroyed) {
+			reject(new HttpError(408, "Request body timeout"));
+			return;
+		}
+		let done = false;
+		const timer = timeoutMs === 0 ? null : setTimeout(() => req.destroy(), timeoutMs);
+		const finish = (error) => {
+			if (done) return;
+			done = true;
+			if (timer) clearTimeout(timer);
+			req.off("data", onData);
+			req.off("end", onEnd);
+			req.off("error", onAbort);
+			req.off("close", onAbort);
+			req.destroy();
+			if (error) reject(error);
+			else resolve(chunks.length === 1 ? chunks[0] : Buffer$1.concat(chunks, bytes));
+		};
+		const onData = (chunk) => {
+			bytes += chunk.length;
+			if (bytes > upfrontLimit) {
+				finish(new HttpError(413, "Payload Too Large"));
+				return;
+			}
+			if (bytes > maxInflated) {
+				finish(new HttpError(413, "Inflated body too large"));
+				return;
+			}
+			timer?.refresh();
+			chunks.push(chunk);
+		};
+		const onEnd = () => finish();
+		const onAbort = () => finish(new HttpError(408, "Request body timeout"));
+		req.on("data", onData);
+		req.on("end", onEnd);
+		req.on("error", onAbort);
+		req.on("close", onAbort);
+		req.resume();
+	});
+}
 /** @internal Exported for test pre-seeding — use {@link seedRawBody} instead. */
 const rawBodySlot = cached(async (ctx) => {
 	const req = ctx.get(httpKind.keys.req);
@@ -414,6 +486,14 @@ const rawBodySlot = cached(async (ctx) => {
 	const upfrontLimit = isZip ? maxCompressed : maxInflated;
 	if (cl && cl > upfrontLimit) throw new HttpError(413, "Payload Too Large");
 	for (const enc of encs) if (!compressors[enc]) throw new HttpError(415, `Unsupported Content-Encoding "${enc}"`);
+	if (!streamable) {
+		const raw = await readRawBody(req, upfrontLimit, maxInflated, timeoutMs);
+		if (!isZip) return raw;
+		const body = await uncompressBody(encs, raw);
+		if (body.byteLength > maxInflated) throw new HttpError(413, "Inflated body too large");
+		if (raw.byteLength > 0 && body.byteLength / raw.byteLength > maxRatio) throw new HttpError(413, "Compression ratio too high");
+		return body;
+	}
 	let timer = null;
 	function resetTimer() {
 		if (timeoutMs === 0) return;
@@ -446,8 +526,7 @@ const rawBodySlot = cached(async (ctx) => {
 			clearTimer();
 		}
 	}
-	let stream = limitedCompressed();
-	if (streamable) stream = await uncompressBodyStream(encs, stream);
+	const stream = await uncompressBodyStream(encs, limitedCompressed());
 	const chunks = [];
 	let inflatedBytes = 0;
 	try {
@@ -460,14 +539,8 @@ const rawBodySlot = cached(async (ctx) => {
 		if (error instanceof HttpError) throw error;
 		throw new HttpError(408, "Request body timeout");
 	}
-	let body = Buffer$1.concat(chunks);
-	if (!streamable && isZip) {
-		body = await uncompressBody(encs, body);
-		inflatedBytes = body.byteLength;
-		if (inflatedBytes > maxInflated) throw new HttpError(413, "Inflated body too large");
-	}
-	if (isZip && rawBytes > 0 && inflatedBytes / rawBytes > maxRatio) throw new HttpError(413, "Compression ratio too high");
-	return body;
+	if (rawBytes > 0 && inflatedBytes / rawBytes > maxRatio) throw new HttpError(413, "Compression ratio too high");
+	return Buffer$1.concat(chunks);
 });
 const forwardedIpSlot = cached((ctx) => {
 	const req = ctx.get(httpKind.keys.req);
@@ -563,19 +636,6 @@ function seedRawBody(ctx, raw) {
 	if (ctx.parent) ctx.getOwn(useRequest._slot);
 }
 
-//#endregion
-//#region packages/event-http/src/composables/headers.ts
-/**
-* Returns the incoming request headers.
-* @example
-* ```ts
-* const { host, authorization } = useHeaders()
-* ```
-*/
-function useHeaders(ctx) {
-	return useRequest(ctx).headers;
-}
-
 //#endregion
 //#region packages/event-http/src/composables/response.ts
 /**
@@ -734,6 +794,70 @@ const cookieAttrFunc = {
 	sameSite: (v) => v ? `SameSite=${typeof v === "string" ? v : "Strict"}` : ""
 };
 
+//#endregion
+//#region packages/event-http/src/response/prerender.ts
+const registry = /* @__PURE__ */ new WeakMap();
+function weakEtag(json) {
+	return `W/"${createHash("sha256").update(json).digest("base64url").slice(0, 22)}"`;
+}
+/**
+* Serializes `obj` to JSON once and remembers the string by object identity. Whenever a handler
+* (or an interceptor) responds with that same object, the response reuses the stored JSON instead
+* of calling `JSON.stringify` again. Use it for large, long-lived response objects that many
+* requests return as is — e.g. a schema or metadata envelope built once and cached.
+*
+* With `{ etag: true }` a weak `ETag` is derived from the serialized bytes; a `GET`/`HEAD`
+* that responds `200` with the object sets the `ETag` header and answers a matching
+* `If-None-Match` with `304 Not Modified` (no body; other headers such as `Cache-Control`
+* and `Vary` are kept). Error responses never become `304`. An `ETag` header set explicitly
+* on the response wins and disables the `304` handling for that response.
+*
+* **Contract: never mutate a registered object (or anything it references).** The stored JSON
+* is not refreshed, so a mutation would keep serving the old bytes. Build a new object instead —
+* freezing registered objects (`Object.freeze`, deeply) in development makes violations throw.
+*
+* Calling it again for the same object is a no-op (it adds the `ETag` if it was not requested
+* the first time). Entries are held weakly and disappear with the object.
+*
+* @param obj - A JSON-serializable object or array
+* @param options - `{ etag: true }` to also compute a weak ETag
+* @returns The same `obj`, so it can wrap a return value
+*
+* @example
+* ```ts
+* const envelope = prerenderJson(Object.freeze(buildMeta()), { etag: true })
+* app.get('/meta', () => {
+*   useResponse().setHeader('cache-control', 'private, no-cache')
+*   return envelope // sent without re-serializing; 304 on a matching If-None-Match
+* })
+* ```
+*/
+function prerenderJson(obj, options) {
+	let entry = registry.get(obj);
+	if (!entry) {
+		const json = JSON.stringify(obj);
+		if (typeof json !== "string") throw new TypeError("prerenderJson: value does not serialize to JSON");
+		entry = { json };
+		registry.set(obj, entry);
+	}
+	if (options?.etag && !entry.etag) entry.etag = weakEtag(entry.json);
+	return obj;
+}
+/** @internal Returns the pre-serialized JSON (and weak ETag) registered for `obj`, if any. */
+function getPrerenderedJson(obj) {
+	return registry.get(obj);
+}
+/** @internal Weak comparison of `etag` against an `If-None-Match` header value. */
+function ifNoneMatchHas(header, etag) {
+	if (!header) return false;
+	const opaque = etag.startsWith("W/") ? etag.slice(2) : etag;
+	for (const part of header.split(",")) {
+		const tag = part.trim();
+		if (tag === "*" || (tag.startsWith("W/") ? tag.slice(2) : tag) === opaque) return true;
+	}
+	return false;
+}
+
 //#endregion
 //#region packages/event-http/src/response/http-response.ts
 const hasFetchResponse = typeof globalThis.Response === "function";
@@ -772,8 +896,6 @@ var HttpResponse = class {
 		this._status = 0;
 		this._body = void 0;
 		this._headers = {};
-		this._cookies = {};
-		this._rawCookies = [];
 		this._hasCookies = false;
 		this._responded = false;
 		if (defaultHeaders) for (const key in defaultHeaders) this._headers[key] = defaultHeaders[key];
@@ -841,7 +963,7 @@ var HttpResponse = class {
 	}
 	/** Sets an outgoing `Set-Cookie` header with optional attributes (chainable). */
 	setCookie(name, value, attrs) {
-		this._cookies[name] = {
+		(this._cookies ??= {})[name] = {
 			value,
 			attrs: attrs || {}
 		};
@@ -850,23 +972,23 @@ var HttpResponse = class {
 	}
 	/** Returns a previously set cookie's data, or `undefined` if not set. */
 	getCookie(name) {
-		return this._cookies[name];
+		return this._cookies?.[name];
 	}
 	/** Removes a cookie from the outgoing set list (chainable). */
 	removeCookie(name) {
-		delete this._cookies[name];
+		if (this._cookies) delete this._cookies[name];
 		return this;
 	}
 	/** Removes all outgoing cookies (chainable). */
 	clearCookies() {
-		this._cookies = {};
-		this._rawCookies = [];
+		this._cookies = void 0;
+		this._rawCookies = void 0;
 		this._hasCookies = false;
 		return this;
 	}
 	/** Appends a raw `Set-Cookie` header string (chainable). Use when you need full control over the cookie format. */
 	setCookieRaw(rawValue) {
-		this._rawCookies.push(rawValue);
+		(this._rawCookies ??= []).push(rawValue);
 		this._hasCookies = true;
 		return this;
 	}
@@ -881,8 +1003,10 @@ var HttpResponse = class {
 	*/
 	getSetCookieStrings() {
 		const rendered = [];
-		for (const [name, data] of Object.entries(this._cookies)) if (data) rendered.push(renderCookie(name, data));
-		rendered.push(...this._rawCookies);
+		if (this._cookies) {
+			for (const [name, data] of Object.entries(this._cookies)) if (data) rendered.push(renderCookie(name, data));
+		}
+		if (this._rawCookies) rendered.push(...this._rawCookies);
 		return rendered;
 	}
 	/** Sets the `Cache-Control` header from a directive object (chainable). */
@@ -944,6 +1068,10 @@ var HttpResponse = class {
 		}
 		const rendered = this.renderBody();
 		this.autoStatus(!!rendered);
+		if (this.applyPrerenderedEtag()) return new globalThis.Response(null, {
+			status: this._status,
+			headers: this._buildWebHeaders()
+		});
 		if (rendered) {
 			const contentLength = typeof rendered === "string" ? Buffer.byteLength(rendered) : rendered.byteLength;
 			this._headers["content-length"] = contentLength.toString();
@@ -992,6 +1120,11 @@ var HttpResponse = class {
 		if (body instanceof Uint8Array) return body;
 		if (typeof body === "object") {
 			if (!this._headers["content-type"]) this._headers["content-type"] = "application/json";
+			const prerendered = getPrerenderedJson(body);
+			if (prerendered) {
+				this._prerenderedEtag = prerendered.etag;
+				return prerendered.json;
+			}
 			return JSON.stringify(body);
 		}
 		throw new Error(`Unsupported body format "${typeof body}"`);
@@ -1043,6 +1176,31 @@ var HttpResponse = class {
 		}
 		this._hasCookies = false;
 	}
+	/**
+	* For a body registered with `prerenderJson(obj, { etag: true })`: sets the `ETag` header on a
+	* GET/HEAD 2xx response (unless one was set explicitly) and turns a `200` whose `If-None-Match`
+	* matches into a bodiless `304`. Returns `true` when the response became `304`.
+	* Other methods get no ETag (a validator on e.g. a PUT response would describe the stored resource).
+	*/
+	applyPrerenderedEtag() {
+		const etag = this._prerenderedEtag;
+		if (!etag) return false;
+		this._prerenderedEtag = void 0;
+		const method = this._req.method;
+		if (method !== "GET" && method !== "HEAD" || this._status < 200 || this._status > 299 || this.hasHeaderIgnoreCase("etag")) return false;
+		this._headers.etag = etag;
+		if (this._status !== EHttpStatusCode.OK || !ifNoneMatchHas(this._req.headers["if-none-match"], etag)) return false;
+		this._status = EHttpStatusCode.NotModified;
+		for (const key in this._headers) {
+			const lower = key.toLowerCase();
+			if (lower === "content-type" || lower === "content-length") delete this._headers[key];
+		}
+		return true;
+	}
+	hasHeaderIgnoreCase(name) {
+		for (const key in this._headers) if (key.toLowerCase() === name) return true;
+		return false;
+	}
 	autoStatus(hasBody) {
 		if (this._status) return;
 		if (!hasBody) {
@@ -1090,6 +1248,10 @@ var HttpResponse = class {
 	sendRegular(method) {
 		const renderedBody = this.renderBody();
 		this.autoStatus(!!renderedBody);
+		if (this.applyPrerenderedEtag()) {
+			this._res.writeHead(this._status, this._headers).end();
+			return;
+		}
 		const contentLength = typeof renderedBody === "string" ? Buffer.byteLength(renderedBody) : renderedBody.byteLength;
 		this._headers["content-length"] = contentLength.toString();
 		this._res.writeHead(this._status, this._headers).end(method === "HEAD" ? "" : renderedBody);
@@ -1468,7 +1630,7 @@ function escapeHtml(value) {
 //#endregion
 //#region packages/event-http/src/response/wooks-http-response.ts
 let framework = {
-	version: "0.7.26",
+	version: "0.7.27",
 	poweredBy: "wooksjs",
 	link: "https://wooks.moost.org/",
 	image: "https://wooks.moost.org/wooks-full-logo.svg"
@@ -1492,7 +1654,8 @@ var WooksHttpResponse = class extends HttpResponse {
 	}
 	renderError(data, ctx) {
 		this._status = data.statusCode || 500;
-		const { has } = useAccept(ctx);
+		const accept = ctx.get(httpKind.keys.req).headers.accept;
+		const has = (type) => acceptHeaderHas(accept, type);
 		if (has("json")) {
 			this._headers["content-type"] = "application/json";
 			this._body = JSON.stringify(data);
@@ -1788,33 +1951,19 @@ var WooksHttp = class extends WooksAdapterBase {
 		}
 	}
 	async processAsyncResult(promise, handlers, startIndex, ctx, response) {
-		try {
-			const result = await promise;
-			await this.respond(result, response, ctx);
+		for (let i = startIndex; i < handlers.length; i++) try {
+			const result = await (i === startIndex ? promise : handlers[i]());
+			const sent = this.respond(result, response, ctx);
+			if (sent) await sent;
 			return result;
 		} catch (error) {
-			const isLastHandler = startIndex === handlers.length - 1;
 			if (!(error instanceof HttpError)) this.logger.error(`Uncaught route handler exception: ${ctx.get(httpKind.keys.req)?.url || ""}`, error);
-			if (isLastHandler) {
-				await this.respond(error, response, ctx);
+			if (i === handlers.length - 1) {
+				const sent = this.respond(error, response, ctx);
+				if (sent) await sent;
 				return error;
 			}
 		}
-		for (let i = startIndex + 1; i < handlers.length; i++) {
-			const handler = handlers[i];
-			const isLastHandler = i === handlers.length - 1;
-			try {
-				const result = await handler();
-				await this.respond(result, response, ctx);
-				return result;
-			} catch (error) {
-				if (!(error instanceof HttpError)) this.logger.error(`Uncaught route handler exception: ${ctx.get(httpKind.keys.req)?.url || ""}`, error);
-				if (isLastHandler) {
-					await this.respond(error, response, ctx);
-					return error;
-				}
-			}
-		}
 	}
 	/**
 	* Programmatic route invocation using the Web Standard fetch API.
@@ -2087,4 +2236,4 @@ function prepareTestHttpContext(options) {
 }
 
 //#endregion
-export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useLogger, useRequest, useResponse, useRouteParams, useUrlParams };
+export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, prerenderJson, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useLogger, useRequest, useResponse, useRouteParams, useUrlParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-http",
-  "version": "0.7.26",
+  "version": "0.7.27",
   "description": "@wooksjs/event-http",
   "keywords": [
     "api",
@@ -42,14 +42,14 @@
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.7",
-    "@wooksjs/event-core": "^0.7.26",
-    "wooks": "^0.7.26"
+    "@wooksjs/event-core": "^0.7.27",
+    "wooks": "^0.7.27"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
-    "@prostojs/router": "^0.3.4",
-    "@wooksjs/event-core": "^0.7.26",
-    "wooks": "^0.7.26"
+    "@prostojs/router": "^0.3.5",
+    "wooks": "^0.7.27",
+    "@wooksjs/event-core": "^0.7.27"
   },
   "scripts": {
     "build": "rolldown -c ../../rolldown.config.mjs"