@schmock/core 2.2.3 → 2.3.0

package/src/builder.ts

@@ -1,4 +1,5 @@
 import type { Server } from "node:http";
+import { isBinaryBody } from "./binary.js";
 import { normalizePath, toHttpMethod } from "./constants.js";
 import {
   errorMessage,
@@ -14,7 +15,11 @@ import {
 } from "./http-helpers.js";
 import { createFetchInterceptor } from "./interceptor.js";
 import { parseRouteKey } from "./parser.js";
-import { runPluginPipeline } from "./plugin-pipeline.js";
+import {
+  recoverGeneratorError,
+  runPluginBeforeRequest,
+  runPluginPipeline,
+} from "./plugin-pipeline.js";
 import { parseResponse } from "./response-parser.js";
 import type { CompiledCallableRoute } from "./route-matcher.js";
 import {
@@ -104,8 +109,8 @@ export class CallableMockInstance {
       ) {
         // Default to plain text for primitives
         routeConfig.contentType = "text/plain";
-      } else if (Buffer.isBuffer(generator)) {
-        // Default to octet-stream for buffers
+      } else if (isBinaryBody(generator)) {
+        // Default to octet-stream for browser and Node binary values
         routeConfig.contentType = "application/octet-stream";
       } else {
         // Default to JSON for objects/arrays
@@ -394,8 +399,16 @@ export class CallableMockInstance {
     this.server = httpServer;
 
     return new Promise((resolve, reject) => {
-      httpServer.on("error", reject);
+      const handleStartupError = (error: Error) => {
+        if (this.server === httpServer) {
+          this.server = undefined;
+          this.serverInfo = undefined;
+        }
+        reject(error);
+      };
+      httpServer.once("error", handleStartupError);
       httpServer.listen(port, hostname, () => {
+        httpServer.off("error", handleStartupError);
         const addr = httpServer.address();
         const actualPort =
           addr !== null && typeof addr === "object" ? addr.port : port;
@@ -485,7 +498,7 @@ export class CallableMockInstance {
           const response = {
             status: 404,
             body: { error: error.message, code: error.code },
-            headers: {},
+            headers: { "content-type": "application/json" },
           };
           this.emit("request:end", {
             method,
@@ -520,7 +533,7 @@ export class CallableMockInstance {
         const response = {
           status: 404,
           body: { error: error.message, code: error.code },
-          headers: {},
+          headers: { "content-type": "application/json" },
         };
         this.emit("request:end", {
           method,
@@ -547,25 +560,8 @@ export class CallableMockInstance {
         params,
       });
 
-      // Generate initial response from route handler
-      const context: Schmock.RequestContext = {
-        method,
-        path: requestPath,
-        params,
-        query: reqQuery,
-        headers: reqHeaders,
-        body: options?.body,
-        state: this.globalConfig.state || {},
-      };
-
-      let result: unknown;
-      if (isGeneratorFunction(matchedRoute.generator)) {
-        result = await matchedRoute.generator(context);
-      } else {
-        result = matchedRoute.generator;
-      }
-
-      // Build plugin context
+      // Build plugin context before route code so request guards can reject
+      // invalid or unauthorized requests without triggering side effects.
       let pluginContext: Schmock.PluginContext = {
         path: requestPath,
         route: matchedRoute.config,
@@ -578,16 +574,66 @@ export class CallableMockInstance {
         routeState: this.globalConfig.state || {},
       };
 
+      const preflightResult = await runPluginBeforeRequest(
+        this.plugins,
+        pluginContext,
+        this.logger,
+      );
+      pluginContext = preflightResult.context;
+      if (preflightResult.requestShortCircuited === true) {
+        pluginContext = { ...pluginContext, requestShortCircuited: true };
+      }
+
+      let result: unknown = preflightResult.response;
+      let skipPostProcessing = preflightResult.recoveredFromError === true;
+
+      if (result === undefined) {
+        const context: Schmock.RequestContext = {
+          method: pluginContext.method,
+          path: pluginContext.path,
+          params: pluginContext.params,
+          query: pluginContext.query,
+          headers: pluginContext.headers,
+          body: pluginContext.body,
+          state: pluginContext.routeState ?? this.globalConfig.state ?? {},
+        };
+
+        try {
+          if (isGeneratorFunction(matchedRoute.generator)) {
+            result = await matchedRoute.generator(context);
+          } else {
+            result = matchedRoute.generator;
+          }
+        } catch (error) {
+          const recovery = await recoverGeneratorError(
+            this.plugins,
+            pluginContext,
+            error,
+            this.logger,
+          );
+          pluginContext = recovery.context;
+          result = recovery.response;
+          skipPostProcessing = recovery.recoveredFromError === true;
+        }
+      }
+
       // Run plugin pipeline to transform the response
       try {
-        const pipelineResult = await runPluginPipeline(
-          this.plugins,
-          pluginContext,
-          result,
-          this.logger,
-        );
-        pluginContext = pipelineResult.context;
-        result = pipelineResult.response;
+        if (skipPostProcessing) {
+          this.logger.log(
+            "pipeline",
+            "Skipping response processors after error recovery",
+          );
+        } else {
+          const pipelineResult = await runPluginPipeline(
+            this.plugins,
+            pluginContext,
+            result,
+            this.logger,
+          );
+          pluginContext = pipelineResult.context;
+          result = pipelineResult.response;
+        }
       } catch (error) {
         this.logger.log(
           "error",
@@ -659,7 +705,7 @@ export class CallableMockInstance {
           error: errorMessage(error),
           code: error instanceof SchmockError ? error.code : "INTERNAL_ERROR",
         },
-        headers: {},
+        headers: { "content-type": "application/json" },
       };
 
       // Apply delay even for error responses
@@ -691,10 +737,11 @@ export class CallableMockInstance {
       return;
     }
 
-    const ms = Array.isArray(effectiveDelay)
+    const configuredMs = Array.isArray(effectiveDelay)
       ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
         effectiveDelay[0]
       : effectiveDelay;
+    const ms = Math.max(0, configuredMs);
 
     await new Promise((resolve) => setTimeout(resolve, ms));
   }

package/src/http-helpers.test.ts

@@ -0,0 +1,39 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { collectBody } from "./http-helpers.js";
+
+function bodyStream(body: Buffer): PassThrough {
+  const stream = new PassThrough();
+  stream.end(body);
+  return stream;
+}
+
+describe("collectBody size limits", () => {
+  it("accepts a body exactly at the configured limit", async () => {
+    const body = Buffer.from("12345");
+    await expect(collectBody(bodyStream(body), {}, body.length)).resolves.toBe(
+      "12345",
+    );
+  });
+
+  it("accepts and parses JSON below the configured limit", async () => {
+    const body = Buffer.from('{"ok":true}');
+    await expect(
+      collectBody(
+        bodyStream(body),
+        { "content-type": "application/json" },
+        body.length + 1,
+      ),
+    ).resolves.toEqual({ ok: true });
+  });
+
+  it("rejects a body above the configured limit with status 413", async () => {
+    const body = Buffer.from("123456");
+    await expect(
+      collectBody(bodyStream(body), {}, body.length - 1),
+    ).rejects.toMatchObject({
+      message: "Request body too large",
+      status: 413,
+    });
+  });
+});

package/src/http-helpers.ts

@@ -1,10 +1,26 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServerResponse } from "node:http";
+import { isBinaryBody } from "./binary.js";
+
+interface RequestWithHeaders {
+  readonly headers: {
+    readonly [header: string]: string | string[] | undefined;
+  };
+}
+
+interface BodyReadable {
+  on(event: "error", listener: (error: Error) => void): this;
+  on(event: "data", listener: (chunk: Buffer) => void): this;
+  on(event: "end", listener: () => void): this;
+  destroy(error?: Error): this;
+}
 
 /**
  * Convert Node.js IncomingMessage headers to a flat Record<string, string>.
  * Drops array-valued headers (keeps only string values).
  */
-export function parseNodeHeaders(req: IncomingMessage): Record<string, string> {
+export function parseNodeHeaders(
+  req: RequestWithHeaders,
+): Record<string, string> {
   const headers: Record<string, string> = {};
   for (const [key, value] of Object.entries(req.headers)) {
     if (typeof value === "string") {
@@ -37,7 +53,7 @@ const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
  * @param maxBodySize - Maximum body size in bytes (default: 10 MB)
  */
 export function collectBody(
-  req: IncomingMessage,
+  req: BodyReadable,
   headers: Record<string, string>,
   maxBodySize = DEFAULT_MAX_BODY_SIZE,
 ): Promise<unknown> {
@@ -93,20 +109,40 @@ export function writeSchmockResponse(
     ...extraHeaders,
   };
 
+  const hasContentType = Object.keys(responseHeaders).some(
+    (header) => header.toLowerCase() === "content-type",
+  );
+
   if (
-    !responseHeaders["content-type"] &&
+    !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 responseBody =
-    response.body === undefined
-      ? undefined
-      : typeof response.body === "string"
-        ? response.body
-        : JSON.stringify(response.body);
+  let responseBody: string | Uint8Array | undefined;
+  if (response.body === undefined) {
+    responseBody = undefined;
+  } else if (typeof response.body === "string") {
+    responseBody = response.body;
+  } else if (response.body instanceof ArrayBuffer) {
+    responseBody = new Uint8Array(response.body);
+  } else if (ArrayBuffer.isView(response.body)) {
+    responseBody = new Uint8Array(
+      response.body.buffer,
+      response.body.byteOffset,
+      response.body.byteLength,
+    );
+  } else {
+    responseBody = JSON.stringify(response.body);
+  }
 
   res.writeHead(response.status, responseHeaders);
   res.end(responseBody);

package/src/index.ts

@@ -80,6 +80,7 @@ export function schmock(
   return callableInstance;
 }
 
+export { isBinaryBody } from "./binary.js";
 // Re-export constants and utilities
 export {
   HTTP_METHODS,

package/src/interceptor.test.ts

@@ -26,6 +26,83 @@ describe("mock.intercept()", () => {
     handle.restore();
   });
 
+  it("returns browser binary bodies without JSON serialization", async () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    mock("GET /api/binary", bytes);
+    const handle = mock.intercept();
+
+    try {
+      const response = await fetch("http://localhost/api/binary");
+      expect(response.headers.get("content-type")).toBe(
+        "application/octet-stream",
+      );
+      expect(new Uint8Array(await response.arrayBuffer())).toEqual(bytes);
+    } finally {
+      handle.restore();
+    }
+  });
+
+  it("returns dynamic binary bodies with binary content type", async () => {
+    const bytes = new Uint8Array([4, 5, 6]);
+    mock("GET /api/dynamic-binary", () => bytes.buffer);
+    const handle = mock.intercept();
+
+    try {
+      const response = await fetch("http://localhost/api/dynamic-binary");
+      expect(response.headers.get("content-type")).toBe(
+        "application/octet-stream",
+      );
+      expect(new Uint8Array(await response.arrayBuffer())).toEqual(bytes);
+    } finally {
+      handle.restore();
+    }
+  });
+
+  it("returns tuple binary bodies with binary content type", async () => {
+    const bytes = new Uint8Array([7, 8, 9]);
+    mock(
+      "GET /api/tuple-binary",
+      () => [206, new DataView(bytes.buffer)] satisfies [number, unknown],
+    );
+    const handle = mock.intercept();
+
+    try {
+      const response = await fetch("http://localhost/api/tuple-binary");
+      expect(response.status).toBe(206);
+      expect(response.headers.get("content-type")).toBe(
+        "application/octet-stream",
+      );
+      expect(new Uint8Array(await response.arrayBuffer())).toEqual(bytes);
+    } finally {
+      handle.restore();
+    }
+  });
+
+  it("normalizes a binary body supplied by beforeResponse", async () => {
+    mock("GET /api/source", "source");
+    const sharedBytes = new Uint8Array(new SharedArrayBuffer(3));
+    sharedBytes.set([10, 11, 12]);
+    const handle = mock.intercept({
+      beforeResponse: () => ({
+        status: 200,
+        body: new DataView(sharedBytes.buffer),
+        headers: {},
+      }),
+    });
+
+    try {
+      const response = await fetch("http://localhost/api/source");
+      expect(response.headers.get("content-type")).toBe(
+        "application/octet-stream",
+      );
+      expect(new Uint8Array(await response.arrayBuffer())).toEqual(
+        new Uint8Array([10, 11, 12]),
+      );
+    } finally {
+      handle.restore();
+    }
+  });
+
   it("passes through unmatched routes when passthrough is true", async () => {
     mock("GET /api/users", [{ id: 1 }]);
     // Save reference to the vi.fn() mock that the interceptor will call on passthrough
@@ -288,4 +365,124 @@ describe("mock.intercept()", () => {
 
     handle.restore();
   });
+
+  it("composes mock instances newest-first and chains passthrough", async () => {
+    const olderMock = schmock();
+    olderMock("GET /api/shared", { source: "older" });
+    olderMock("GET /api/older", { source: "older" });
+
+    const newerMock = schmock();
+    newerMock("GET /api/shared", { source: "newer" });
+
+    const olderHandle = olderMock.intercept();
+    const newerHandle = newerMock.intercept();
+
+    try {
+      const sharedResponse = await fetch("http://localhost/api/shared");
+      expect(await sharedResponse.json()).toEqual({ source: "newer" });
+
+      const olderResponse = await fetch("http://localhost/api/older");
+      expect(await olderResponse.json()).toEqual({ source: "older" });
+    } finally {
+      newerHandle.restore();
+      olderHandle.restore();
+    }
+  });
+
+  it("keeps remaining interceptors installed after out-of-order restore", async () => {
+    const baseline = globalThis.fetch;
+    const olderMock = schmock();
+    const newerMock = schmock();
+    newerMock("GET /api/newer", { source: "newer" });
+
+    const olderHandle = olderMock.intercept();
+    const newerHandle = newerMock.intercept();
+
+    olderHandle.restore();
+    expect(olderHandle.active).toBe(false);
+    expect(newerHandle.active).toBe(true);
+    expect(globalThis.fetch).not.toBe(baseline);
+
+    try {
+      const response = await fetch("http://localhost/api/newer");
+      expect(await response.json()).toEqual({ source: "newer" });
+    } finally {
+      newerHandle.restore();
+    }
+
+    expect(globalThis.fetch).toBe(baseline);
+  });
+
+  it("restores idempotently", () => {
+    const baseline = globalThis.fetch;
+    const handle = mock.intercept();
+
+    handle.restore();
+    handle.restore();
+
+    expect(handle.active).toBe(false);
+    expect(globalThis.fetch).toBe(baseline);
+  });
+
+  it("does not overwrite a fetch replacement installed after Schmock", () => {
+    const handle = mock.intercept();
+    const replacementFetch = vi
+      .fn()
+      .mockResolvedValue(new Response("third-party backend"));
+    globalThis.fetch = replacementFetch;
+
+    handle.restore();
+
+    expect(globalThis.fetch).toBe(replacementFetch);
+  });
+
+  it("keeps a third-party wrapper's captured dispatcher usable", async () => {
+    const baseline = globalThis.fetch;
+    const handle = mock.intercept();
+    const schmockDispatcher = globalThis.fetch;
+    const replacementFetch = vi.fn(
+      (input: RequestInfo | URL, init?: RequestInit) =>
+        schmockDispatcher(input, init),
+    );
+    globalThis.fetch = replacementFetch;
+
+    handle.restore();
+
+    const response = await fetch("http://localhost/real-backend");
+    expect(await response.text()).toBe("real backend");
+    expect(replacementFetch).toHaveBeenCalledOnce();
+    expect(baseline).toHaveBeenCalledOnce();
+  });
+
+  it("wraps the current fetch when a later interceptor follows a replacement", async () => {
+    const olderMock = schmock();
+    olderMock("GET /api/older", { source: "older" });
+    const olderHandle = olderMock.intercept();
+
+    const replacementFetch = vi
+      .fn()
+      .mockResolvedValue(new Response("third-party backend"));
+    globalThis.fetch = replacementFetch;
+
+    const newerMock = schmock();
+    newerMock("GET /api/newer", { source: "newer" });
+    const newerHandle = newerMock.intercept();
+
+    olderHandle.restore();
+    expect(olderHandle.active).toBe(false);
+    expect(newerHandle.active).toBe(true);
+
+    try {
+      const mockedResponse = await fetch("http://localhost/api/newer");
+      expect(await mockedResponse.json()).toEqual({ source: "newer" });
+
+      const passthroughResponse = await fetch("http://localhost/real-backend");
+      expect(await passthroughResponse.text()).toBe("third-party backend");
+      expect(replacementFetch).toHaveBeenCalledOnce();
+    } finally {
+      newerHandle.restore();
+    }
+
+    expect(globalThis.fetch).toBe(replacementFetch);
+  });
 });