Add runtime response header validation with OpenAPI hot-reload

.changeset/giant-drinks-joke.md

@@ -0,0 +1,5 @@
+---
+"counterfact": minor
+---
+
+Validate response headers at runtime and report type errors as `response-type-error` HTTP headers (one per error, multiple headers with the same name). Use --no-validate-response to disable.

bin/counterfact.js

@@ -113,12 +113,12 @@
   // helper.ts is imported via .js extension — the TypeScript convention used
   // throughout this codebase. If the runtime resolves helper.js → helper.ts,
   // it is fully capable of running the TypeScript source tree.
   fs.writeFileSync(
     nodePath.join(dir, "helper.ts"),
     'export const value: string = "ok";\n',
     "utf8",
   );
   fs.writeFileSync(
     nodePath.join(dir, "main.ts"),
     'import { value } from "./helper.js"; export default value;\n',
     "utf8",
@@ -293,7 +293,7 @@
     const optionSource = program.getOptionValueSource(key);
 
     if (optionSource !== "cli") {
       options[key] = value;
     }
   }
 
@@ -327,7 +327,7 @@
     )
   ) {
     for (const action of actions) {
       options[action] = true;
     }
   }
 
@@ -377,6 +377,7 @@
     startServer: options.serve,
     buildCache: options.buildCache || false,
     validateRequests: options.validateRequest !== false,
+    validateResponses: options.validateResponse !== false,
 
     watch: {
       routes: options.watch || options.watchRoutes,
@@ -402,15 +403,15 @@
   let didMigrate = false;
   let didMigrateRouteTypes;
 
   if (fs.existsSync(nodePath.join(config.basePath, "paths"))) {
     await pathsToRoutes(config.basePath);
     await fs.promises.rmdir(nodePath.join(config.basePath, "paths"), {
       recursive: true,
     });
     await fs.promises.rmdir(nodePath.join(config.basePath, "path-types"), {
       recursive: true,
     });
     await fs.promises.rmdir(nodePath.join(config.basePath, "components"), {
       recursive: true,
     });
 
@@ -584,6 +585,10 @@
     "--no-validate-request",
     "disable request validation against the OpenAPI spec",
   )
+  .option(
+    "--no-validate-response",
+    "disable response validation against the OpenAPI spec",
+  )
   .option(
     "--config <path>",
     "path to a counterfact.yaml config file (default: counterfact.yaml in the current directory)",

docs/faq.md

@@ -164,6 +164,12 @@ Yes, by default. Requests that don't match the schema defined in the spec return
 
 ---
 
+## Does it validate outgoing responses?
+
+Yes, by default. Response headers are validated against the schema defined in the spec. Any validation errors (missing required headers or type mismatches) are reported as `response-type-error` HTTP response headers — one header per error; multiple headers with the same name are allowed. The response body is still returned normally — the errors are advisory only. Disable this with `--no-validate-response` if you need looser behavior.
+
+---
+
 ## What OpenAPI versions are supported?
 
 OpenAPI 3.x. Swagger 2 (OAS2) is not currently supported.

docs/reference.md

@@ -285,6 +285,7 @@ npx counterfact@latest [spec] [output] [options]
 | `--proxy-url <url>` | _(none)_ | Default upstream for the proxy |
 | `--prefix <path>` | _(none)_ | Global path prefix (e.g. `/api/v1`) |
 | `--no-validate-request` | `false` | Skip OpenAPI request validation |
+| `--no-validate-response` | `false` | Skip OpenAPI response header validation |
 | `--generate-types` | `false` | Generate types only |
 | `--generate-routes` | `false` | Generate routes only |
 | `--watch-types` | `false` | Watch and regenerate types only |

src/server/config.ts

@@ -17,6 +17,7 @@ export interface Config {
   startRepl: boolean;
   startServer: boolean;
   validateRequests: boolean;
+  validateResponses: boolean;
   watch: {
     routes: boolean;
     types: boolean;

src/server/dispatcher.ts

@@ -11,6 +11,7 @@ import type {
 } from "./registry.js";
 import { createResponseBuilder } from "./response-builder.js";
 import { validateRequest } from "./request-validator.js";
+import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 import type {
   OpenApiOperation,
@@ -384,6 +385,20 @@ export class Dispatcher {
       };
     }
 
+    if (this.config?.validateResponses !== false) {
+      const validation = validateResponse(operation, normalizedResponse);
+
+      if (!validation.valid) {
+        return {
+          ...normalizedResponse,
+          headers: {
+            ...normalizedResponse.headers,
+            "response-type-error": validation.errors,
+          },
+        };
+      }
+    }
+
     return normalizedResponse;
   }
 }

src/server/response-validator.ts

@@ -0,0 +1,96 @@
+import Ajv from "ajv";
+
+import type { OpenApiOperation } from "../counterfact-types/index.js";
+import type { CounterfactResponseObject } from "./registry.js";
+
+const ajv = new Ajv({
+  allErrors: true,
+  strict: false,
+  coerceTypes: false,
+});
+
+export interface ResponseValidationResult {
+  errors: string[];
+  valid: boolean;
+}
+
+export function validateResponse(
+  operation: OpenApiOperation | undefined,
+  response: CounterfactResponseObject,
+): ResponseValidationResult {
+  if (!operation) {
+    return { errors: [], valid: true };
+  }
+
+  const errors: string[] = [];
+
+  const statusKey =
+    response.status !== undefined ? String(response.status) : undefined;
+
+  const responseSpec =
+    (statusKey !== undefined ? operation.responses[statusKey] : undefined) ??
+    operation.responses.default;
+
+  if (!responseSpec) {
+    return { errors: [], valid: true };
+  }
+
+  const specHeaders = responseSpec.headers ?? {};
+  const actualHeaders = response.headers ?? {};
+
+  for (const [name, headerSpec] of Object.entries(specHeaders)) {
+    const actualValue =
+      actualHeaders[name] ?? actualHeaders[name.toLowerCase()];
+
+    if (headerSpec.required === true && actualValue === undefined) {
+      errors.push(`response header '${name}' is required`);
+      continue;
+    }
+
+    if (actualValue !== undefined && headerSpec.schema !== undefined) {
+      const coercedValue =
+        typeof actualValue === "string"
+          ? coerceHeaderValue(actualValue, headerSpec.schema)
+          : actualValue;
+
+      const valid = ajv.validate(headerSpec.schema, coercedValue);
+
+      if (!valid && ajv.errors) {
+        for (const error of ajv.errors) {
+          const path = error.instancePath ?? "";
+
+          errors.push(
+            `response header '${name}'${path} ${error.message ?? "is invalid"}`,
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    errors,
+    valid: errors.length === 0,
+  };
+}
+
+function coerceHeaderValue(
+  value: string,
+  schema: { [key: string]: unknown },
+): unknown {
+  const type = schema.type as string | undefined;
+
+  if (type === "integer" || type === "number") {
+    const num = Number(value);
+
+    return Number.isNaN(num) ? value : num;
+  }
+
+  if (type === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+
+    return value;
+  }
+
+  return value;
+}

test/server/dispatcher.test.ts

@@ -1220,7 +1220,10 @@ describe("given a request that contains the differently cased path", () => {
       },
     };
 
-    function makeDispatcher(validateRequests: boolean) {
+    function makeDispatcher(
+      validateRequests: boolean,
+      validateResponses = true,
+    ) {
       const registry = new Registry();
 
       registry.add("/widgets", {
@@ -1244,6 +1247,7 @@ describe("given a request that contains the differently cased path", () => {
         startRepl: false,
         startServer: true,
         validateRequests,
+        validateResponses,
         watch: { routes: false, types: false },
       });
     }
@@ -1349,4 +1353,134 @@ describe("given a request that contains the differently cased path", () => {
       expect(response.status).toBe(200);
     });
   });
+
+  describe("response validation", () => {
+    const openApiDocument: OpenApiDocument = {
+      paths: {
+        "/widgets": {
+          get: {
+            responses: {
+              200: {
+                content: { "text/plain": { schema: { type: "string" } } },
+                headers: {
+                  "x-required-header": {
+                    required: true,
+                    schema: { type: "string" },
+                  },
+                  "x-count": {
+                    required: false,
+                    schema: { type: "integer" },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    function makeResponseDispatcher(
+      validateResponses: boolean,
+      handlerHeaders: Record<string, string> = {},
+    ) {
+      const registry = new Registry();
+
+      registry.add("/widgets", {
+        GET() {
+          return { body: "ok", headers: handlerHeaders, status: 200 };
+        },
+      });
+
+      return new Dispatcher(registry, new ContextRegistry(), openApiDocument, {
+        adminApiToken: "",
+        alwaysFakeOptionals: false,
+        basePath: "/",
+        buildCache: false,
+        generate: { routes: false, types: false },
+        openApiPath: "",
+        port: 3100,
+        proxyPaths: new Map(),
+        proxyUrl: "",
+        routePrefix: "",
+        startAdminApi: false,
+        startRepl: false,
+        startServer: true,
+        validateRequests: false,
+        validateResponses,
+        watch: { routes: false, types: false },
+      });
+    }
+
+    it("adds response-type-error headers when a required response header is missing", async () => {
+      const dispatcher = makeResponseDispatcher(true);
+
+      const response = await dispatcher.request({
+        body: "",
+        headers: {},
+        method: "GET",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      const errors = response.headers?.["response-type-error"];
+      const firstError = Array.isArray(errors) ? errors[0] : errors;
+
+      expect(firstError).toContain("x-required-header");
+    });
+
+    it("adds response-type-error headers when a response header has the wrong type", async () => {
+      const dispatcher = makeResponseDispatcher(true, {
+        "x-required-header": "present",
+        "x-count": "not-a-number",
+      });
+
+      const response = await dispatcher.request({
+        body: "",
+        headers: {},
+        method: "GET",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      const errors = response.headers?.["response-type-error"];
+      const firstError = Array.isArray(errors) ? errors[0] : errors;
+
+      expect(firstError).toContain("x-count");
+    });
+
+    it("does not add error headers when all required response headers are present and valid", async () => {
+      const dispatcher = makeResponseDispatcher(true, {
+        "x-required-header": "present",
+        "x-count": "42",
+      });
+
+      const response = await dispatcher.request({
+        body: "",
+        headers: {},
+        method: "GET",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      expect(response.headers?.["response-type-error"]).toBeUndefined();
+    });
+
+    it("skips response validation when validateResponses is false", async () => {
+      const dispatcher = makeResponseDispatcher(false);
+
+      const response = await dispatcher.request({
+        body: "",
+        headers: {},
+        method: "GET",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      expect(response.headers?.["response-type-error"]).toBeUndefined();
+    });
+  });
 });

test/server/koa-middleware.test.ts

@@ -31,6 +31,8 @@ const CONFIG: Config = {
   },
   alwaysFakeOptionals: false,
   buildCache: false,
+  validateRequests: true,
+  validateResponses: true,
 };
 
 const mockKoaProxy = (path: string, { target }: IBaseKoaProxiesOptions) =>