@schmock/core 2.2.2 → 2.3.0

package/src/plugin-pipeline.ts

@@ -1,4 +1,3 @@
-import { isStatusTuple } from "./constants.js";
 import { errorMessage, PluginError } from "./errors.js";
 
 /** Structural typing — DebugLogger satisfies this without an import */
@@ -6,6 +5,138 @@ interface PipelineLogger {
   log(category: string, message: string, data?: unknown): void;
 }
 
+interface PipelineResult {
+  context: Schmock.PluginContext;
+  response?: unknown;
+  recoveredFromError?: boolean;
+  requestShortCircuited?: boolean;
+}
+
+function isPluginResult(value: unknown): value is Schmock.PluginResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "context" in value &&
+    typeof value.context === "object" &&
+    value.context !== null
+  );
+}
+
+async function recoverPluginError(
+  plugins: Schmock.Plugin[],
+  startIndex: number,
+  error: unknown,
+  context: Schmock.PluginContext,
+  logger: PipelineLogger,
+): Promise<
+  { handled: true; response: unknown } | { handled: false; error: Error }
+> {
+  let currentError =
+    error instanceof Error ? error : new Error(errorMessage(error));
+
+  for (let index = startIndex; index < plugins.length; index += 1) {
+    const plugin = plugins[index];
+    if (!plugin.onError) continue;
+
+    try {
+      const errorResult = await plugin.onError(currentError, context);
+      if (errorResult instanceof Error) {
+        currentError = errorResult;
+        continue;
+      }
+      if (errorResult !== undefined) {
+        logger.log("pipeline", `Plugin ${plugin.name} handled error`);
+        return { handled: true, response: errorResult };
+      }
+    } catch (hookError) {
+      currentError =
+        hookError instanceof Error
+          ? hookError
+          : new Error(errorMessage(hookError));
+      logger.log(
+        "pipeline",
+        `Plugin ${plugin.name} error handler failed: ${errorMessage(hookError)}`,
+      );
+    }
+  }
+
+  return { handled: false, error: currentError };
+}
+
+/** Run request guards before route code is allowed to execute. */
+export async function runPluginBeforeRequest(
+  plugins: Schmock.Plugin[],
+  context: Schmock.PluginContext,
+  logger: PipelineLogger,
+): Promise<PipelineResult> {
+  let currentContext = context;
+
+  for (let index = 0; index < plugins.length; index += 1) {
+    const plugin = plugins[index];
+    if (!plugin.beforeRequest) continue;
+
+    logger.log("pipeline", `Running beforeRequest: ${plugin.name}`);
+    try {
+      const result = await plugin.beforeRequest(currentContext);
+      if (result === undefined) continue;
+      if (!isPluginResult(result)) {
+        throw new Error(`Plugin ${plugin.name} didn't return valid result`);
+      }
+
+      currentContext = result.context;
+      if (result.response !== undefined) {
+        logger.log("pipeline", `Plugin ${plugin.name} rejected request`);
+        return {
+          context: currentContext,
+          response: result.response,
+          requestShortCircuited: true,
+        };
+      }
+    } catch (error) {
+      logger.log(
+        "pipeline",
+        `Plugin ${plugin.name} beforeRequest failed: ${errorMessage(error)}`,
+      );
+      const recovery = await recoverPluginError(
+        plugins,
+        index,
+        error,
+        currentContext,
+        logger,
+      );
+      if (recovery.handled) {
+        return {
+          context: currentContext,
+          response: recovery.response,
+          recoveredFromError: true,
+          requestShortCircuited: true,
+        };
+      }
+      throw new PluginError(plugin.name, recovery.error);
+    }
+  }
+
+  return { context: currentContext };
+}
+
+/** Give pipeline error handlers a chance to recover a route-generator error. */
+export async function recoverGeneratorError(
+  plugins: Schmock.Plugin[],
+  context: Schmock.PluginContext,
+  error: unknown,
+  logger: PipelineLogger,
+): Promise<PipelineResult> {
+  const recovery = await recoverPluginError(plugins, 0, error, context, logger);
+  if (recovery.handled) {
+    return {
+      context,
+      response: recovery.response,
+      recoveredFromError: true,
+    };
+  }
+  throw recovery.error;
+}
+
 /**
  * Run all registered plugins in sequence
  * First plugin to set response becomes generator, subsequent plugins transform
@@ -16,7 +147,7 @@ export async function runPluginPipeline(
   context: Schmock.PluginContext,
   initialResponse: unknown,
   logger: PipelineLogger,
-): Promise<{ context: Schmock.PluginContext; response?: unknown }> {
+): Promise<PipelineResult> {
   let currentContext = context;
   let response: unknown = initialResponse;
 
@@ -25,13 +156,14 @@ export async function runPluginPipeline(
     `Running plugin pipeline for ${plugins.length} plugins`,
   );
 
-  for (const plugin of plugins) {
+  for (let index = 0; index < plugins.length; index += 1) {
+    const plugin = plugins[index];
     logger.log("pipeline", `Processing plugin: ${plugin.name}`);
 
     try {
       const result = await plugin.process(currentContext, response);
 
-      if (!result?.context) {
+      if (!isPluginResult(result)) {
         throw new Error(`Plugin ${plugin.name} didn't return valid result`);
       }
 
@@ -54,48 +186,21 @@ export async function runPluginPipeline(
         `Plugin ${plugin.name} failed: ${errorMessage(error)}`,
       );
 
-      // Try error handling if plugin has onError hook
-      if (plugin.onError) {
-        try {
-          const pluginError =
-            error instanceof Error ? error : new Error(errorMessage(error));
-          const errorResult = await plugin.onError(pluginError, currentContext);
-          if (errorResult) {
-            logger.log("pipeline", `Plugin ${plugin.name} handled error`);
-
-            // Error return → transform the thrown error
-            if (errorResult instanceof Error) {
-              throw new PluginError(plugin.name, errorResult);
-            }
-
-            // ResponseResult return → recover, stop pipeline
-            // Accept both object-with-status and status tuple [code, body] / [code, body, headers]
-            if (
-              isStatusTuple(errorResult) ||
-              (typeof errorResult === "object" &&
-                errorResult !== null &&
-                "status" in errorResult)
-            ) {
-              response = errorResult;
-              break;
-            }
-          }
-          // void/falsy return → propagate original error below
-        } catch (hookError) {
-          // If the hook itself threw (including our PluginError above), re-throw it
-          if (hookError instanceof PluginError) {
-            throw hookError;
-          }
-          logger.log(
-            "pipeline",
-            `Plugin ${plugin.name} error handler failed: ${errorMessage(hookError)}`,
-          );
-        }
+      const recovery = await recoverPluginError(
+        plugins,
+        index,
+        error,
+        currentContext,
+        logger,
+      );
+      if (recovery.handled) {
+        return {
+          context: currentContext,
+          response: recovery.response,
+          recoveredFromError: true,
+        };
       }
-
-      const cause =
-        error instanceof Error ? error : new Error(errorMessage(error));
-      throw new PluginError(plugin.name, cause);
+      throw new PluginError(plugin.name, recovery.error);
     }
   }
 

package/src/plugin-system.test.ts

@@ -86,6 +86,57 @@ describe("plugin system", () => {
   });
 
   describe("plugin execution pipeline", () => {
+    it("runs request guards before the route generator", async () => {
+      const mock = schmock();
+      const generator = vi.fn(() => ({ created: true }));
+      const guard: Schmock.Plugin = {
+        name: "guard",
+        beforeRequest(context) {
+          return {
+            context,
+            response: [401, { code: "AUTH_REQUIRED" }],
+          };
+        },
+        process: (context, currentResponse) => ({
+          context,
+          response: currentResponse,
+        }),
+      };
+
+      mock("POST /guarded", generator).pipe(guard);
+
+      const response = await mock.handle("POST", "/guarded");
+      expect(response.status).toBe(401);
+      expect(response.body).toEqual({ code: "AUTH_REQUIRED" });
+      expect(generator).not.toHaveBeenCalled();
+    });
+
+    it("passes pre-request context changes into the generator", async () => {
+      const mock = schmock();
+      const plugin: Schmock.Plugin = {
+        name: "request-transformer",
+        beforeRequest(context) {
+          return {
+            context: {
+              ...context,
+              headers: { ...context.headers, "x-added": "yes" },
+            },
+          };
+        },
+        process: (context, currentResponse) => ({
+          context,
+          response: currentResponse,
+        }),
+      };
+
+      mock("GET /context", ({ headers }) => ({
+        added: headers["x-added"],
+      })).pipe(plugin);
+
+      const response = await mock.handle("GET", "/context");
+      expect(response.body).toEqual({ added: "yes" });
+    });
+
     it("passes context between plugins", async () => {
       const mock = schmock();
       let receivedContext: any;
@@ -251,6 +302,50 @@ describe("plugin system", () => {
   });
 
   describe("plugin error handling", () => {
+    it("allows a downstream error handler to recover an earlier failure", async () => {
+      const mock = schmock();
+      const failingPlugin: Schmock.Plugin = {
+        name: "failing",
+        process() {
+          throw new Error("failed");
+        },
+      };
+      const recoveryPlugin: Schmock.Plugin = {
+        name: "recovery",
+        process: (context, currentResponse) => ({
+          context,
+          response: currentResponse,
+        }),
+        onError: () => [503, { code: "RECOVERED" }],
+      };
+
+      mock("GET /recover", "original").pipe(failingPlugin).pipe(recoveryPlugin);
+
+      const response = await mock.handle("GET", "/recover");
+      expect(response.status).toBe(503);
+      expect(response.body).toEqual({ code: "RECOVERED" });
+    });
+
+    it("allows a plugin error handler to recover a generator failure", async () => {
+      const mock = schmock();
+      const recoveryPlugin: Schmock.Plugin = {
+        name: "generator-recovery",
+        process: (context, currentResponse) => ({
+          context,
+          response: currentResponse,
+        }),
+        onError: () => [502, { code: "GENERATOR_RECOVERED" }],
+      };
+
+      mock("GET /generator-failure", () => {
+        throw new Error("generator failed");
+      }).pipe(recoveryPlugin);
+
+      const response = await mock.handle("GET", "/generator-failure");
+      expect(response.status).toBe(502);
+      expect(response.body).toEqual({ code: "GENERATOR_RECOVERED" });
+    });
+
     it("throws PluginError when plugin process fails", async () => {
       const mock = schmock();
 

package/src/response-parser.ts

@@ -1,5 +1,14 @@
+import { isBinaryBody } from "./binary.js";
 import { isStatusTuple } from "./constants.js";
 
+const BINARY_CONTENT_TYPE = "application/octet-stream";
+
+function hasContentType(headers: Record<string, string>): boolean {
+  return Object.keys(headers).some(
+    (header) => header.toLowerCase() === "content-type",
+  );
+}
+
 function isResponseObject(value: unknown): value is {
   status: number;
   body: unknown;
@@ -9,8 +18,19 @@ function isResponseObject(value: unknown): value is {
     typeof value === "object" &&
     value !== null &&
     "status" in value &&
-    typeof (value as Record<string, unknown>).status === "number" &&
-    "body" in value
+    typeof value.status === "number" &&
+    "body" in value &&
+    (!("headers" in value) ||
+      value.headers === undefined ||
+      isStringRecord(value.headers))
+  );
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.values(value).every((entry) => typeof entry === "string")
   );
 }
 
@@ -30,15 +50,12 @@ export function parseResponse(
 
   // Handle already-formed response objects (from plugin error recovery)
   if (isResponseObject(result)) {
-    return {
-      status: result.status,
-      body: result.body,
-      headers: result.headers || {},
-    };
-  }
-
-  // Handle tuple response format [status, body, headers?]
-  if (isStatusTuple(result)) {
+    status = result.status;
+    body = result.body;
+    headers = result.headers ?? {};
+    tupleFormat = true;
+  } else if (isStatusTuple(result)) {
+    // Handle tuple response format [status, body, headers?]
     [status, body, headers = {}] = result;
     tupleFormat = true;
   }
@@ -52,18 +69,40 @@ export function parseResponse(
     body = undefined; // Ensure body is undefined for null responses
   }
 
+  const binaryBody = isBinaryBody(body);
+
+  // Binary response values need a transport-safe MIME type. Tuple headers still
+  // take precedence, while a non-JSON route override (for example image/png)
+  // remains authoritative for non-tuple responses.
+  if (!hasContentType(headers) && binaryBody) {
+    headers["content-type"] =
+      !tupleFormat &&
+      routeConfig.contentType &&
+      routeConfig.contentType !== "application/json"
+        ? routeConfig.contentType
+        : BINARY_CONTENT_TYPE;
+  }
+
   // Add content-type header from route config if it exists and headers don't already have it
   // But only if this isn't a tuple response (where headers are explicitly controlled)
-  if (!headers["content-type"] && routeConfig.contentType && !tupleFormat) {
+  let appliedRouteContentType = false;
+  if (!hasContentType(headers) && routeConfig.contentType && !tupleFormat) {
     headers["content-type"] = routeConfig.contentType;
+    appliedRouteContentType = true;
+  }
 
-    // Handle special conversion cases when contentType is explicitly set
-    if (routeConfig.contentType === "text/plain" && body !== undefined) {
-      if (typeof body === "object" && !Buffer.isBuffer(body)) {
-        body = JSON.stringify(body);
-      } else if (typeof body !== "string") {
-        body = String(body);
-      }
+  // Handle special conversion cases when contentType is explicitly set. A
+  // binary body keeps its bytes even when a custom MIME type is configured.
+  if (
+    appliedRouteContentType &&
+    routeConfig.contentType === "text/plain" &&
+    body !== undefined &&
+    !binaryBody
+  ) {
+    if (typeof body === "object") {
+      body = JSON.stringify(body);
+    } else if (typeof body !== "string") {
+      body = String(body);
     }
   }
 

package/src/server.test.ts

@@ -1,3 +1,4 @@
+import { createServer } from "node:http";
 import { afterEach, describe, expect, it } from "vitest";
 import { schmock } from "./index";
 
@@ -71,6 +72,53 @@ describe("Standalone Server", () => {
     expect(res.status).toBe(204);
   });
 
+  it("writes binary response bodies without JSON serialization", async () => {
+    mock = schmock();
+    mock("GET /binary", new Uint8Array([0, 1, 255]));
+    const info = await mock.listen(0);
+
+    const response = await fetch(`http://127.0.0.1:${info.port}/binary`);
+    expect(response.headers.get("content-type")).toBe(
+      "application/octet-stream",
+    );
+    expect(new Uint8Array(await response.arrayBuffer())).toEqual(
+      new Uint8Array([0, 1, 255]),
+    );
+  });
+
+  it("writes dynamic and tuple binary responses with binary content type", async () => {
+    mock = schmock();
+    const dynamicBytes = new Uint8Array([1, 2, 3]);
+    const tupleBytes = new Uint8Array([4, 5, 6]);
+    mock("GET /dynamic-binary", () => dynamicBytes.buffer);
+    mock(
+      "GET /tuple-binary",
+      () => [206, new DataView(tupleBytes.buffer)] satisfies [number, unknown],
+    );
+    const info = await mock.listen(0);
+
+    const dynamicResponse = await fetch(
+      `http://127.0.0.1:${info.port}/dynamic-binary`,
+    );
+    expect(dynamicResponse.headers.get("content-type")).toBe(
+      "application/octet-stream",
+    );
+    expect(new Uint8Array(await dynamicResponse.arrayBuffer())).toEqual(
+      dynamicBytes,
+    );
+
+    const tupleResponse = await fetch(
+      `http://127.0.0.1:${info.port}/tuple-binary`,
+    );
+    expect(tupleResponse.status).toBe(206);
+    expect(tupleResponse.headers.get("content-type")).toBe(
+      "application/octet-stream",
+    );
+    expect(new Uint8Array(await tupleResponse.arrayBuffer())).toEqual(
+      tupleBytes,
+    );
+  });
+
   it("reset stops the server", async () => {
     mock = schmock();
     mock("GET /test", { ok: true });
@@ -81,12 +129,9 @@ describe("Standalone Server", () => {
 
     mock.reset();
 
-    try {
-      await fetch(`http://127.0.0.1:${info.port}/test`);
-      expect.unreachable("Should have thrown");
-    } catch {
-      // Expected: connection refused
-    }
+    await expect(
+      fetch(`http://127.0.0.1:${info.port}/test`),
+    ).rejects.toBeDefined();
   });
 
   it("handles route params in server mode", async () => {
@@ -106,6 +151,33 @@ describe("Standalone Server", () => {
     expect(() => mock.listen(0)).toThrow("Server is already running");
   });
 
+  it("can retry listening after an occupied-port failure", async () => {
+    const occupiedServer = createServer();
+    await new Promise<void>((resolve, reject) => {
+      occupiedServer.once("error", reject);
+      occupiedServer.listen(0, "127.0.0.1", resolve);
+    });
+
+    try {
+      const address = occupiedServer.address();
+      if (address === null || typeof address === "string") {
+        throw new Error("Expected an address with a numeric port");
+      }
+
+      mock = schmock();
+      await expect(mock.listen(address.port)).rejects.toMatchObject({
+        code: "EADDRINUSE",
+      });
+
+      const retry = await mock.listen(0);
+      expect(retry.port).toBeGreaterThan(0);
+    } finally {
+      await new Promise<void>((resolve) =>
+        occupiedServer.close(() => resolve()),
+      );
+    }
+  });
+
   it("close is idempotent", async () => {
     mock = schmock();
     mock("GET /test", { ok: true });
@@ -155,11 +227,8 @@ describe("Standalone Server", () => {
     mock.close();
 
     // Subsequent request should fail immediately (not hang on keep-alive)
-    try {
-      await fetch(`http://127.0.0.1:${info.port}/test`);
-      expect.unreachable("Should have thrown");
-    } catch {
-      // Expected: connection refused
-    }
+    await expect(
+      fetch(`http://127.0.0.1:${info.port}/test`),
+    ).rejects.toBeDefined();
   });
 });

package/src/steps/async-support.steps.ts

@@ -5,6 +5,10 @@ import type { CallableMockInstance, Plugin } from "../types";
 
 const feature = await loadFeature("../../features/async-support.feature");
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 describeFeature(feature, ({ Scenario }) => {
   let mock: CallableMockInstance;
   let response: any;
@@ -110,18 +114,30 @@ describeFeature(feature, ({ Scenario }) => {
       mock = schmock();
       const syncPlugin: Plugin = {
         name: "sync-step",
-        process: (ctx, response) => ({
-          context: ctx,
-          response: { ...response, syncStep: true },
-        }),
+        process: (ctx, pluginResponse) => {
+          if (!isRecord(pluginResponse)) {
+            throw new Error(
+              "Expected the sync plugin response to be an object",
+            );
+          }
+          return {
+            context: ctx,
+            response: { ...pluginResponse, syncStep: true },
+          };
+        },
       };
       const asyncPlugin: Plugin = {
         name: "async-step",
-        process: async (ctx, response) => {
+        process: async (ctx, pluginResponse) => {
           await new Promise(resolve => setTimeout(resolve, 5));
+          if (!isRecord(pluginResponse)) {
+            throw new Error(
+              "Expected the async plugin response to be an object",
+            );
+          }
           return {
             context: ctx,
-            response: { ...response, asyncStep: true },
+            response: { ...pluginResponse, asyncStep: true },
           };
         },
       };
@@ -365,13 +381,18 @@ describeFeature(feature, ({ Scenario }) => {
       };
       const plugin2: Plugin = {
         name: "async-step-2",
-        process: async (ctx, response) => {
+        process: async (ctx, pluginResponse) => {
           await new Promise(resolve => setTimeout(resolve, 3));
           const step1Status = ctx.state.get("step1");
+          if (!isRecord(pluginResponse)) {
+            throw new Error(
+              "Expected the stateful plugin response to be an object",
+            );
+          }
           return {
             context: ctx,
             response: {
-              ...response,
+              ...pluginResponse,
               step1: step1Status,
               step2: "completed",
             },