@schmock/core 2.4.1 → 2.6.0

package/dist/http-helpers.js

@@ -1,5 +1,7 @@
-import { isBinaryBody } from "./binary.js";
-import { serializeResponseBody } from "./response-normalizer.js";
+import { HTTP_METHODS, isHttpMethod } from "./constants.js";
+import { SchmockError } from "./errors.js";
+import { getHeader, hasHeader } from "./headers.js";
+import { buildJsonErrorResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
 /** An HTTP client error raised while collecting an incoming request body. */
 export class HttpIngressError extends Error {
     status;
@@ -23,6 +25,7 @@ export function parseNodeHeaders(req) {
 }
 /**
  * Extract query parameters from a URL as a flat Record<string, string>.
+ * A repeated key resolves to its LAST value; every adapter follows this rule.
  */
 export function parseNodeQuery(url) {
     // Own-property definition for the same reason as parseNodeHeaders, and it
@@ -30,7 +33,7 @@ export function parseNodeQuery(url) {
     return Object.fromEntries(url.searchParams);
 }
 /** Default body size limit: 10 MB */
-const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 const DECIMAL_CONTENT_LENGTH = /^\d+$/;
 function payloadTooLargeError() {
     return new HttpIngressError(413, "PAYLOAD_TOO_LARGE", "Request body too large");
@@ -40,21 +43,109 @@ function requestAbortedError() {
     error.name = "AbortError";
     return error;
 }
-function isJsonMediaType(contentType) {
-    const baseMediaType = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
-    return (baseMediaType === "application/json" || baseMediaType.endsWith("+json"));
+/**
+ * Deepest JSON nesting a request body may carry. A body nested far deeper
+ * parses fine but cannot be serialized back (JSON.stringify overflows the
+ * stack), so a handler that stores it poisons every later response that
+ * includes it. Rejecting it at ingress keeps that from ever happening.
+ */
+const MAX_JSON_BODY_DEPTH = 256;
+function baseMediaTypeOf(contentType) {
+    return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isJsonMediaType(mediaType) {
+    return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+/** Whether a parsed JSON value nests deeper than `maxDepth` containers. */
+function exceedsJsonDepth(value, maxDepth) {
+    const pending = [
+        { value, depth: 0 },
+    ];
+    for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+        if (typeof next.value !== "object" || next.value === null)
+            continue;
+        const depth = next.depth + 1;
+        if (depth > maxDepth)
+            return true;
+        for (const child of Object.values(next.value)) {
+            pending.push({ value: child, depth });
+        }
+    }
+    return false;
+}
+function parseJsonBody(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new HttpIngressError(400, "MALFORMED_JSON", "Malformed JSON request body");
+    }
+    if (exceedsJsonDepth(parsed, MAX_JSON_BODY_DEPTH)) {
+        throw new HttpIngressError(400, "JSON_TOO_DEEP", `JSON request body nests deeper than ${MAX_JSON_BODY_DEPTH} levels`);
+    }
+    return parsed;
+}
+async function parseMultipartBody(bytes, contentType) {
+    try {
+        return await new Response(bytes, {
+            headers: { "content-type": contentType },
+        }).formData();
+    }
+    catch {
+        throw new HttpIngressError(400, "MALFORMED_MULTIPART", "Malformed multipart request body");
+    }
+}
+/**
+ * Turn the collected bytes into the body shape the fetch interceptor gives
+ * the same request, so `mock.listen()`, the CLI and `mock.intercept()` hand a
+ * handler the same value:
+ *
+ * - `application/json` and `+json`: the parsed value
+ * - `application/x-www-form-urlencoded`: a flat object, last duplicate wins
+ * - `text/*`: a UTF-8 string
+ * - `multipart/*`: `FormData`
+ * - anything else, including no content type: an `ArrayBuffer`
+ */
+function decodeRequestBody(bytes, contentType) {
+    const mediaType = baseMediaTypeOf(contentType);
+    if (isJsonMediaType(mediaType)) {
+        return parseJsonBody(new TextDecoder().decode(bytes));
+    }
+    if (mediaType === "application/x-www-form-urlencoded") {
+        return Object.fromEntries(new URLSearchParams(new TextDecoder().decode(bytes)));
+    }
+    if (mediaType.startsWith("text/")) {
+        return new TextDecoder().decode(bytes);
+    }
+    if (mediaType.startsWith("multipart/")) {
+        return parseMultipartBody(bytes, contentType);
+    }
+    return bytes.buffer;
+}
+/** Copy the chunks into one buffer that the body exclusively owns. */
+function concatChunks(chunks, totalSize) {
+    const bytes = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
 }
 /**
  * Collect and parse the request body from a Node.js IncomingMessage.
- * Returns parsed JSON for application/json and +json media types, otherwise the
- * raw string.
+ * The body takes the shape the fetch interceptor gives it: parsed JSON for
+ * application/json and +json, an object for urlencoded forms, a string for
+ * text/*, FormData for multipart/*, and an ArrayBuffer for anything else.
  * Returns undefined for empty bodies.
  * @param req - Node.js IncomingMessage
- * @param headers - Parsed request headers
+ * @param headers - Parsed request headers; content-length and content-type
+ *   are looked up case-insensitively
  * @param maxBodySize - Maximum body size in bytes (default: 10 MB)
  */
 export function collectBody(req, headers, maxBodySize = DEFAULT_MAX_BODY_SIZE) {
-    const contentLength = headers["content-length"];
+    const contentLength = getHeader(headers, "content-length");
     const declaredBodyTooLarge = contentLength !== undefined &&
         DECIMAL_CONTENT_LENGTH.test(contentLength) &&
         Number(contentLength) > maxBodySize;
@@ -95,22 +186,19 @@ export function collectBody(req, headers, maxBodySize = DEFAULT_MAX_BODY_SIZE) {
         req.on("end", () => {
             if (settled)
                 return;
-            const raw = Buffer.concat(chunks).toString();
-            if (!raw) {
+            if (totalSize === 0) {
                 resolveOnce(undefined);
                 return;
             }
-            const contentType = headers["content-type"] ?? "";
-            if (isJsonMediaType(contentType)) {
-                try {
-                    resolveOnce(JSON.parse(raw));
-                }
-                catch {
-                    rejectOnce(new HttpIngressError(400, "MALFORMED_JSON", "Malformed JSON request body"));
-                }
+            const bytes = concatChunks(chunks, totalSize);
+            try {
+                // A multipart body decodes asynchronously. Resolving with that promise
+                // settles collection now, so the `close` Node emits right after `end`
+                // cannot pre-empt the parse as an abort.
+                resolveOnce(decodeRequestBody(bytes, getHeader(headers, "content-type") ?? ""));
             }
-            else {
-                resolveOnce(raw);
+            catch (error) {
+                rejectOnce(error instanceof Error ? error : new Error(String(error)));
             }
         });
     });
@@ -119,33 +207,36 @@ export function collectBody(req, headers, maxBodySize = DEFAULT_MAX_BODY_SIZE) {
 const REJECTED_REQUEST_IDLE_MS = 400;
 /** Hard cap for a client that keeps streaming after a rejected request. */
 const REJECTED_REQUEST_DRAIN_GRACE_MS = 5_000;
-function prepareWriteableResponse(response, extraHeaders) {
-    const responseHeaders = { ...response.headers };
-    if (extraHeaders) {
-        const names = new Map(Object.keys(responseHeaders).map((name) => [name.toLowerCase(), name]));
-        for (const [name, value] of Object.entries(extraHeaders)) {
-            const previousName = names.get(name.toLowerCase());
-            if (previousName !== undefined)
-                delete responseHeaders[previousName];
-            responseHeaders[name] = value;
-            names.set(name.toLowerCase(), name);
-        }
+/** Merge `extraHeaders` over `headers`; an extra header replaces any case variant. */
+function mergeExtraHeaders(headers, extraHeaders) {
+    const merged = { ...headers };
+    if (!extraHeaders)
+        return merged;
+    const names = new Map(Object.keys(merged).map((name) => [name.toLowerCase(), name]));
+    for (const [name, value] of Object.entries(extraHeaders)) {
+        const previousName = names.get(name.toLowerCase());
+        if (previousName !== undefined)
+            delete merged[previousName];
+        merged[name] = value;
+        names.set(name.toLowerCase(), name);
     }
-    const hasContentType = Object.keys(responseHeaders).some((header) => header.toLowerCase() === "content-type");
-    if (!hasContentType &&
-        response.body !== undefined &&
-        isBinaryBody(response.body)) {
-        responseHeaders["content-type"] = "application/octet-stream";
-    }
-    else if (!hasContentType &&
-        response.body !== undefined &&
-        typeof response.body !== "string") {
-        responseHeaders["content-type"] = "application/json";
-    }
-    const body = serializeResponseBody({
+    return merged;
+}
+function prepareWriteableResponse(response, extraHeaders) {
+    // Extra headers first, so an extra content type counts before a default one
+    // is inferred; the length is declared last, from the serialized bytes.
+    const typed = withDefaultContentType({
         ...response,
-        headers: responseHeaders,
+        headers: mergeExtraHeaders(response.headers, extraHeaders),
     });
+    const responseHeaders = typed.headers;
+    const body = serializeResponseBody(typed);
+    // Declare the length up front: writeHead() commits the header block before
+    // end() sees the body, so without it Node frames every response as chunked,
+    // unlike Express's res.end(buffer).
+    if (body !== undefined && !hasHeader(responseHeaders, "content-length")) {
+        responseHeaders["content-length"] = String(body.byteLength);
+    }
     return { headers: responseHeaders, body };
 }
 /**
@@ -204,3 +295,194 @@ export function writeRejectedSchmockResponse(req, res, response, extraHeaders) {
     graceTimer.unref?.();
     req.resume();
 }
+/** Placeholder origin for origin-form request targets; never contacted. */
+const REQUEST_TARGET_ORIGIN = "http://schmock.invalid";
+const ALLOWED_METHODS_HEADER = HTTP_METHODS.join(", ");
+/**
+ * A client error `serveNodeRequest` answers before the mock sees the request:
+ * 400 for a request it cannot parse, 405 for a verb Schmock does not route.
+ */
+class NodeRequestError extends SchmockError {
+    status;
+    headers;
+    constructor(status, code, message, headers = {}) {
+        super(message, code);
+        this.status = status;
+        this.headers = headers;
+        this.name = "NodeRequestError";
+    }
+}
+/** Whether a Host header value parses as an authority. */
+function isParseableHost(host) {
+    try {
+        return new URL(`http://${host}`).host !== "";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse a Node request target into a URL without letting it pick the host.
+ *
+ * Resolving an origin-form target (`/path?q`) against a base reads a leading
+ * `//` as a protocol-relative URL: `//users` would become host "users" with
+ * path "/" and be served by `GET /`. Appending it to a fixed origin keeps the
+ * whole target as the path. The asterisk-form (`OPTIONS *`) keeps the `/*`
+ * path it always resolved to; any other target must be an absolute URL.
+ */
+function parseRequestTarget(target) {
+    try {
+        if (target.startsWith("/"))
+            return new URL(`${REQUEST_TARGET_ORIGIN}${target}`);
+        if (target === "*")
+            return new URL(`${REQUEST_TARGET_ORIGIN}/*`);
+        return new URL(target);
+    }
+    catch {
+        throw new NodeRequestError(400, "BAD_REQUEST", "Malformed request target");
+    }
+}
+/**
+ * Check the Host header, then parse the target. The Host must be present and
+ * parse as an authority, but only the target's path and query are used.
+ */
+function parseNodeRequestUrl(req) {
+    const host = req.headers.host;
+    if (!host) {
+        throw new NodeRequestError(400, "BAD_REQUEST", "Missing Host header");
+    }
+    if (!isParseableHost(host)) {
+        throw new NodeRequestError(400, "BAD_REQUEST", "Malformed Host header");
+    }
+    return parseRequestTarget(req.url ?? "/");
+}
+function parseNodeRequestMethod(method) {
+    const upper = (method ?? "GET").toUpperCase();
+    if (!isHttpMethod(upper)) {
+        throw new NodeRequestError(405, "METHOD_NOT_ALLOWED", `Unsupported HTTP method: ${upper}`, { allow: ALLOWED_METHODS_HEADER });
+    }
+    return upper;
+}
+function defaultErrorReply(error) {
+    if (error instanceof NodeRequestError) {
+        return {
+            status: error.status,
+            code: error.code,
+            message: error.message,
+            headers: error.headers,
+        };
+    }
+    if (error instanceof HttpIngressError) {
+        return { status: error.status, code: error.code, message: error.message };
+    }
+    return {
+        status: 500,
+        code: "SERVER_ERROR",
+        message: error instanceof Error ? error.message : "Internal Server Error",
+    };
+}
+/**
+ * Answer a request that failed. TOTAL: an answer that cannot be written
+ * destroys the socket instead, so the client is never left waiting and no
+ * error escapes as an unhandled rejection.
+ */
+function answerFailedRequest(input) {
+    const { req, res, error, method, path, options } = input;
+    try {
+        if (res.headersSent || res.writableEnded) {
+            // Bytes are already on the wire, so no answer can replace them.
+            if (!res.writableEnded)
+                res.end();
+            return;
+        }
+        const reply = options.classifyError?.(error) ?? defaultErrorReply(error);
+        // An ingress failure leaves the request body unread or unusable, so the
+        // connection cannot carry another request. `shouldKeepAlive = false`
+        // alone emits no Connection header when writeHead is given a header
+        // object, so the close is announced explicitly, on the transport's own
+        // header channel: normalizeResponse strips hop-by-hop headers from
+        // everything a route produces.
+        const closeConnection = error instanceof HttpIngressError || reply.status === 413;
+        if (closeConnection)
+            res.shouldKeepAlive = false;
+        const response = buildJsonErrorResponse({
+            status: reply.status,
+            error: reply.message,
+            code: reply.code,
+            method,
+            headers: reply.headers,
+        });
+        const extraHeaders = {
+            ...options.extraHeaders?.({ isError: true, path }),
+            ...(closeConnection ? { connection: "close" } : {}),
+        };
+        if (reply.status === 413) {
+            writeRejectedSchmockResponse(req, res, response, extraHeaders);
+        }
+        else {
+            writeSchmockResponse(res, response, extraHeaders);
+        }
+    }
+    catch {
+        res.destroy();
+    }
+}
+/** Read a parsed request's headers, query and body, then route it. */
+async function handleWithBody(req, url, method, path, options) {
+    const headers = parseNodeHeaders(req);
+    const query = parseNodeQuery(url);
+    const body = await collectBody(req, headers, options.maxBodySize);
+    return options.handle(method, path, {
+        headers,
+        body,
+        query,
+        signal: options.signal,
+    });
+}
+/**
+ * Serve one Node.js request through a mock: the bridge `mock.listen()` runs,
+ * usable with any `http.createServer` callback.
+ *
+ * It rejects a request without a parseable Host header or target (400) and a
+ * method Schmock does not route (405, with `allow`), gives `answerBeforeBody`
+ * the chance to answer without the body, then parses headers, query and body
+ * (400 for a malformed JSON or multipart body, 413 over `maxBodySize`, 10 MB
+ * by default) and calls `handle` with an abort signal that fires when the
+ * client goes away. Every failure is answered as `{ error, code }` JSON; an
+ * ingress failure also closes the connection, and a 413 is flushed while the
+ * client may still be uploading so it can read it.
+ *
+ * The returned promise never rejects. It settles once the response has been
+ * handed to Node, which is when per-request resources (a request admission)
+ * can be released.
+ */
+export async function serveNodeRequest(req, res, options) {
+    const abortController = new AbortController();
+    const abortRequest = () => abortController.abort();
+    req.once("aborted", abortRequest);
+    res.once("close", abortRequest);
+    // The method an error answer is shaped for until the verb parses: a HEAD
+    // request keeps its bodyless answer even when it is rejected.
+    let method = req.method?.toUpperCase() === "HEAD" ? "HEAD" : "GET";
+    let path;
+    try {
+        // Client errors are answered in this order: the target, then the verb.
+        const url = parseNodeRequestUrl(req);
+        path = url.pathname;
+        method = parseNodeRequestMethod(req.method);
+        const response = options.answerBeforeBody?.(method, path) ??
+            (await handleWithBody(req, url, method, path, {
+                handle: options.handle,
+                maxBodySize: options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE,
+                signal: abortController.signal,
+            }));
+        writeSchmockResponse(res, response, options.extraHeaders?.({ isError: false, path }));
+    }
+    catch (error) {
+        answerFailedRequest({ req, res, error, method, path, options });
+    }
+    finally {
+        req.off("aborted", abortRequest);
+        res.off("close", abortRequest);
+    }
+}