Merge pull request #1653 from pmcelhaney/copilot/add-request-validation-feature

Add request validation against OpenAPI spec

Author: pmcelhaney

.changeset/add-request-validation.md

@@ -0,0 +1,5 @@
+---
+"counterfact": minor
+---
+
+Add request validation against the OpenAPI spec. Incoming requests are now validated by default — missing required query parameters, missing required headers, and request bodies that do not match the declared schema all result in a 400 response with a descriptive error message. Validation can be disabled with the `--no-validate-request` CLI flag.

README.md

@@ -205,6 +205,7 @@ npx counterfact@latest [openapi.yaml] [destination] [options]
 | `--spec <path>`     | Path or URL to the OpenAPI document         |
 | `--proxy-url <url>` | Forward all requests to this URL by default |
 | `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
+| `--no-validate-request` | Disable request validation against the OpenAPI spec |
 
 Run `npx counterfact@latest --help` for the full list of options.
 

bin/README.md

@@ -41,5 +41,6 @@ npx counterfact@latest openapi.yaml ./api [options]
 | `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
 | `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
 | `--no-update-check` | Disable the npm update check on startup |
+| `--no-validate-request` | Disable request validation against the OpenAPI spec |
 
 Run `npx counterfact@latest --help` to see the full option list.

bin/counterfact.js

@@ -300,6 +300,7 @@ async function main(source, destination) {
     startRepl: options.repl,
     startServer: options.serve,
     buildCache: options.buildCache || false,
+    validateRequests: options.validateRequest !== false,
 
     watch: {
       routes: options.watch || options.watchRoutes,
@@ -499,5 +500,9 @@ program
     "path or URL to OpenAPI document (alternative to the positional [openapi.yaml] argument)",
   )
   .option("--no-update-check", "disable the npm update check on startup")
+  .option(
+    "--no-validate-request",
+    "disable request validation against the OpenAPI spec",
+  )
   .action(main)
   .parse(process.argv);

package.json

@@ -126,6 +126,7 @@
     "@apidevtools/json-schema-ref-parser": "13.0.5",
     "@hapi/accept": "6.0.3",
     "@types/json-schema": "7.0.15",
+    "ajv": "6.14.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
     "debug": "4.4.3",

src/counterfact-types/index.ts

@@ -255,15 +255,25 @@ type HttpStatusCode =
 interface OpenApiParameters {
   in: "body" | "cookie" | "formData" | "header" | "path" | "query";
   name: string;
+  required?: boolean;
   schema?: {
-    type: string;
+    [key: string]: unknown;
+    type?: string;
   };
   type?: "string" | "number" | "integer" | "boolean";
 }
 
 interface OpenApiOperation {
   parameters?: OpenApiParameters[];
   produces?: string[];
+  requestBody?: {
+    content?: {
+      [mediaType: string]: {
+        schema: { [key: string]: unknown };
+      };
+    };
+    required?: boolean;
+  };
   responses: {
     [status: string]: {
       content?: {

src/server/config.ts

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

src/server/dispatcher.ts

@@ -10,6 +10,7 @@ import type {
   Registry,
 } from "./registry.js";
 import { createResponseBuilder } from "./response-builder.js";
+import { validateRequest } from "./request-validator.js";
 import { Tools } from "./tools.js";
 import type {
   OpenApiOperation,
@@ -297,6 +298,18 @@ export class Dispatcher {
 
     const operation = this.operationForPathAndMethod(matchedPath, method);
 
+    if (this.config?.validateRequests !== false) {
+      const validation = validateRequest(operation, { body, headers, query });
+
+      if (!validation.valid) {
+        return {
+          body: `Request validation failed:\n${validation.errors.join("\n")}`,
+          contentType: "text/plain",
+          status: 400,
+        };
+      }
+    }
+
     const continuousDistribution = (min: number, max: number) => {
       return min + Math.random() * (max - min);
     };

src/server/request-validator.ts

@@ -0,0 +1,95 @@
+import Ajv from "ajv";
+
+import type { OpenApiOperation } from "../counterfact-types/index.js";
+
+const ajv = new Ajv({
+  allErrors: true,
+  unknownFormats: "ignore",
+  coerceTypes: false,
+});
+
+export interface ValidationResult {
+  errors: string[];
+  valid: boolean;
+}
+
+function findMissingRequired(
+  parameters: NonNullable<OpenApiOperation["parameters"]>,
+  location: string,
+  values: Record<string, string>,
+): string[] {
+  return parameters
+    .filter((p) => p.in === location && p.required === true)
+    .filter((p) => !(p.name in values) || values[p.name] === undefined)
+    .map((p) => `${location} parameter '${p.name}' is required`);
+}
+
+export function validateRequest(
+  operation: OpenApiOperation | undefined,
+  request: {
+    body: unknown;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+  },
+): ValidationResult {
+  if (!operation) {
+    return { errors: [], valid: true };
+  }
+
+  const errors: string[] = [];
+  const parameters = operation.parameters ?? [];
+
+  // For query and header parameters, HTTP always delivers values as strings.
+  // Only check that required parameters are present; type coercion is handled
+  // by the registry before the route handler is called.
+  errors.push(...findMissingRequired(parameters, "query", request.query));
+  errors.push(...findMissingRequired(parameters, "header", request.headers));
+
+  // Validate request body (OpenAPI 3.x requestBody)
+  if (operation.requestBody?.content !== undefined) {
+    const schema =
+      operation.requestBody.content["application/json"]?.schema ??
+      operation.requestBody.content["application/x-www-form-urlencoded"]
+        ?.schema;
+
+    if (schema !== undefined) {
+      const valid = ajv.validate(schema, request.body);
+
+      if (!valid && ajv.errors) {
+        for (const error of ajv.errors) {
+          const path =
+            (error as { instancePath?: string }).instancePath ??
+            error.dataPath ??
+            "";
+
+          errors.push(`body${path} ${error.message ?? "is invalid"}`);
+        }
+      }
+    } else if (operation.requestBody.required === true && !request.body) {
+      errors.push("body is required");
+    }
+  }
+
+  // Validate request body (OpenAPI 2.x body parameter)
+  const bodyParam = parameters.find((p) => p.in === "body");
+
+  if (bodyParam?.schema !== undefined) {
+    const valid = ajv.validate(bodyParam.schema, request.body);
+
+    if (!valid && ajv.errors) {
+      for (const error of ajv.errors) {
+        const path =
+          (error as { instancePath?: string }).instancePath ??
+          error.dataPath ??
+          "";
+
+        errors.push(`body${path} ${error.message ?? "is invalid"}`);
+      }
+    }
+  }
+
+  return {
+    errors,
+    valid: errors.length === 0,
+  };
+}

test/server/dispatcher.test.ts

@@ -1186,4 +1186,167 @@ describe("given a request that contains the differently cased path", () => {
 
     expect(response.body).toBe("ok");
   });
+
+  describe("request validation", () => {
+    const openApiDocument: OpenApiDocument = {
+      paths: {
+        "/widgets": {
+          post: {
+            parameters: [
+              { in: "query", name: "required-query", required: true },
+              { in: "query", name: "optional-query" },
+              { in: "header", name: "x-required-header", required: true },
+            ],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    properties: {
+                      name: { type: "string" },
+                    },
+                    required: ["name"],
+                    type: "object",
+                  },
+                },
+              },
+            },
+            responses: {
+              200: {
+                content: { "text/plain": { schema: { type: "string" } } },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    function makeDispatcher(validateRequests: boolean) {
+      const registry = new Registry();
+
+      registry.add("/widgets", {
+        POST() {
+          return { body: "ok", 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,
+        watch: { routes: false, types: false },
+      });
+    }
+
+    it("returns 400 when a required query parameter is missing", async () => {
+      const dispatcher = makeDispatcher(true);
+
+      const response = await dispatcher.request({
+        body: { name: "sprocket" },
+        headers: { "x-required-header": "yes" },
+        method: "POST",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(400);
+      expect(response.body).toContain("required-query");
+    });
+
+    it("returns 400 when a required header is missing", async () => {
+      const dispatcher = makeDispatcher(true);
+
+      const response = await dispatcher.request({
+        body: { name: "sprocket" },
+        headers: {},
+        method: "POST",
+        path: "/widgets",
+        query: { "required-query": "yes" },
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(400);
+      expect(response.body).toContain("x-required-header");
+    });
+
+    it("returns 400 when the request body is missing a required field", async () => {
+      const dispatcher = makeDispatcher(true);
+
+      const response = await dispatcher.request({
+        body: {},
+        headers: { "x-required-header": "yes" },
+        method: "POST",
+        path: "/widgets",
+        query: { "required-query": "yes" },
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(400);
+      expect(response.body).toContain("name");
+    });
+
+    it("returns 200 when all required parameters and body are valid", async () => {
+      const dispatcher = makeDispatcher(true);
+
+      const response = await dispatcher.request({
+        body: { name: "sprocket" },
+        headers: { "x-required-header": "yes" },
+        method: "POST",
+        path: "/widgets",
+        query: { "required-query": "yes" },
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(200);
+    });
+
+    it("skips validation when validateRequests is false", async () => {
+      const dispatcher = makeDispatcher(false);
+
+      const response = await dispatcher.request({
+        body: {},
+        headers: {},
+        method: "POST",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(200);
+    });
+
+    it("skips validation when there is no OpenAPI document", async () => {
+      const registry = new Registry();
+
+      registry.add("/widgets", {
+        POST() {
+          return { body: "ok", status: 200 };
+        },
+      });
+
+      const dispatcher = new Dispatcher(registry, new ContextRegistry());
+
+      const response = await dispatcher.request({
+        body: {},
+        headers: {},
+        method: "POST",
+        path: "/widgets",
+        query: {},
+        req: { path: "/widgets" },
+      });
+
+      expect(response.status).toBe(200);
+    });
+  });
 });