api-json-server 1.1.0 → 1.2.0

package/src/server.ts

@@ -1,10 +1,16 @@
-import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify";
+import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest, type FastifyBaseLogger } from "fastify";
 import type { MockSpecInferSchema } from "./spec.js";
 import { registerEndpoints } from "./registerEndpoints.js";
 import swaggerUiDist from "swagger-ui-dist";
 import { generateOpenApi } from "./openapi.js";
 import fastifyStatic from "@fastify/static";
+import fastifyCookie from "@fastify/cookie";
+import fastifyCors from "@fastify/cors";
 import YAML from "yaml";
+import { createLogger } from "./logger/customLogger.js";
+import type { LoggerOptions } from "./logger/types.js";
+import { HistoryRecorder } from "./history/historyRecorder.js";
+import type { HistoryFilter } from "./history/types.js";
 
 type SwaggerUiDistModule = {
      getAbsoluteFSPath?: () => string;
@@ -43,11 +49,61 @@ function resolveServerUrl(req: FastifyRequest, baseUrl?: string): string {
  */
 export function buildServer(
      spec: MockSpecInferSchema,
-     meta?: { specPath?: string; loadedAt?: string; baseUrl?: string }
+     meta?: { specPath?: string; loadedAt?: string; baseUrl?: string; logger?: FastifyBaseLogger | boolean }
 ): FastifyInstance {
      const app = Fastify({
-          logger: true,
-          trustProxy: true
+          logger: meta?.logger ?? true,
+          trustProxy: true,
+          disableRequestLogging: false
+     });
+
+     // Register CORS if configured
+     if (spec.settings.cors) {
+          app.register(fastifyCors, {
+               origin: spec.settings.cors.origin ?? true,
+               credentials: spec.settings.cors.credentials ?? false,
+               methods: spec.settings.cors.methods,
+               allowedHeaders: spec.settings.cors.allowedHeaders,
+               exposedHeaders: spec.settings.cors.exposedHeaders,
+               maxAge: spec.settings.cors.maxAge
+          });
+     }
+
+     // Register cookie parser plugin
+     app.register(fastifyCookie);
+
+     // Create history recorder
+     const history = new HistoryRecorder(1000);
+
+     // Record all requests in onRequest hook (after body parsing)
+     app.addHook("preHandler", async (req, reply) => {
+          const startTime = Date.now();
+
+          // Store start time for response hook
+          (req as FastifyRequest & { startTime?: number }).startTime = startTime;
+
+          history.record({
+               method: req.method,
+               url: req.url,
+               path: req.routeOptions?.url ?? req.url.split("?")[0],
+               query: req.query as Record<string, unknown>,
+               headers: req.headers,
+               body: req.body
+          });
+     });
+
+     // Update history with response details in onResponse hook
+     app.addHook("onResponse", async (req, reply) => {
+          const startTime = (req as FastifyRequest & { startTime?: number }).startTime ?? Date.now();
+          const responseTime = Date.now() - startTime;
+
+          // Find and update the last entry (just added in onRequest)
+          const entries = history.query({ limit: 1 });
+          if (entries.length > 0) {
+               const lastEntry = entries[entries.length - 1];
+               lastEntry.statusCode = reply.statusCode;
+               lastEntry.responseTime = responseTime;
+          }
      });
 
      /**
@@ -96,6 +152,23 @@ export function buildServer(
 
      app.get("/docs", docsRouteHandler);
 
+     // History endpoints
+     app.get("/__history", async (req) => {
+          const query = req.query as Record<string, string>;
+          const filter: HistoryFilter = {
+               endpoint: query.endpoint,
+               method: query.method,
+               statusCode: query.statusCode ? Number(query.statusCode) : undefined,
+               limit: query.limit ? Number(query.limit) : undefined
+          };
+          return { entries: history.query(filter), total: history.count() };
+     });
+
+     app.delete("/__history", async () => {
+          history.clear();
+          return { ok: true, message: "History cleared" };
+     });
+
      registerEndpoints(app, spec);
 
      return app;

package/src/spec.ts

@@ -66,18 +66,32 @@ const TemplateValueSchema: z.ZodType<TemplateValue> = z.lazy(() =>
 export const MatchSchema = z.object({
      query: z.record(z.string(), PrimitiveSchema).optional(),
      // Exact match for top-level body fields only (keeps v1 simple)
-     body: z.record(z.string(), PrimitiveSchema).optional()
+     body: z.record(z.string(), PrimitiveSchema).optional(),
+     // Header matching (case-insensitive keys)
+     headers: z.record(z.string(), z.string()).optional(),
+     // Cookie matching
+     cookies: z.record(z.string(), z.string()).optional()
 });
 
+const DelaySchema = z.union([
+     z.number().int().min(0),
+     z.object({
+          min: z.number().int().min(0),
+          max: z.number().int().min(0)
+     })
+]);
+
 export const VariantSchema = z.object({
      name: z.string().min(1).optional(),
      match: MatchSchema.optional(),
 
      status: z.number().int().min(100).max(599).optional(),
      response: TemplateValueSchema,
+     headers: z.record(z.string(), z.string()).optional(),
 
      // Simulation overrides per variant (optional)
      delayMs: z.number().int().min(0).optional(),
+     delay: DelaySchema.optional(),
      errorRate: z.number().min(0).max(1).optional(),
      errorStatus: z.number().int().min(100).max(599).optional(),
      errorResponse: TemplateValueSchema.optional()
@@ -93,9 +107,23 @@ export const EndpointSchema = z.object({
      // Response behavior:
      status: z.number().int().min(200).max(599).default(200),
      response: TemplateValueSchema,
+     headers: z.record(z.string(), z.string()).optional(),
+
+     // Per-endpoint CORS override
+     cors: z
+          .object({
+               origin: z.union([z.string(), z.array(z.string()), z.boolean()]).optional(),
+               credentials: z.boolean().optional(),
+               methods: z.array(z.string()).optional(),
+               allowedHeaders: z.array(z.string()).optional(),
+               exposedHeaders: z.array(z.string()).optional(),
+               maxAge: z.number().int().optional()
+          })
+          .optional(),
 
      // Simulation (optional overrides)
      delayMs: z.number().int().min(0).optional(),
+     delay: DelaySchema.optional(),
      errorRate: z.number().min(0).max(1).optional(),
      errorStatus: z.number().int().min(100).max(599).optional(),
      errorResponse: TemplateValueSchema.optional()
@@ -109,7 +137,17 @@ export const MockSpecSchema = z.object({
                errorRate: z.number().min(0).max(1).default(0),
                errorStatus: z.number().int().min(100).max(599).default(500),
                errorResponse: TemplateValueSchema.default({ error: "Mock error" }),
-               fakerSeed: z.number().int().min(0).optional()
+               fakerSeed: z.number().int().min(0).optional(),
+               cors: z
+                    .object({
+                         origin: z.union([z.string(), z.array(z.string()), z.boolean()]).optional(),
+                         credentials: z.boolean().optional(),
+                         methods: z.array(z.string()).optional(),
+                         allowedHeaders: z.array(z.string()).optional(),
+                         exposedHeaders: z.array(z.string()).optional(),
+                         maxAge: z.number().int().optional()
+                    })
+                    .optional()
           })
           .default({ delayMs: 0, errorRate: 0, errorStatus: 500, errorResponse: { error: "Mock error" } }),
      endpoints: z.array(EndpointSchema).min(1)

package/tests/cors.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("CORS configuration", () => {
+     it("enables CORS with wildcard origin when configured", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: {
+                    ...baseSettings,
+                    cors: {
+                         origin: "*",
+                         credentials: false
+                    }
+               },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/data",
+                         response: { data: "value" }
+                    }
+               ]
+          });
+
+          const res = await app.inject({
+               method: "GET",
+               url: "/api/data",
+               headers: { origin: "https://example.com" }
+          });
+
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["access-control-allow-origin"]).toBe("*");
+
+          await app.close();
+     });
+
+     it("handles preflight OPTIONS requests", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: {
+                    ...baseSettings,
+                    cors: {
+                         origin: "https://example.com",
+                         methods: ["GET", "POST"],
+                         credentials: true
+                    }
+               },
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/api/data",
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          const res = await app.inject({
+               method: "OPTIONS",
+               url: "/api/data",
+               headers: {
+                    origin: "https://example.com",
+                    "access-control-request-method": "POST"
+               }
+          });
+
+          expect(res.statusCode).toBe(204);
+          expect(res.headers["access-control-allow-origin"]).toBeTruthy();
+
+          await app.close();
+     });
+
+     it("allows specific origins when configured", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: {
+                    ...baseSettings,
+                    cors: {
+                         origin: "https://trusted.com",
+                         credentials: true
+                    }
+               },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/secure",
+                         response: { data: "secure" }
+                    }
+               ]
+          });
+
+          const res = await app.inject({
+               method: "GET",
+               url: "/api/secure",
+               headers: { origin: "https://trusted.com" }
+          });
+
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["access-control-allow-origin"]).toBe("https://trusted.com");
+          expect(res.headers["access-control-allow-credentials"]).toBe("true");
+
+          await app.close();
+     });
+
+     it("works without CORS configuration", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/data",
+                         response: { data: "value" }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/api/data" });
+          expect(res.statusCode).toBe(200);
+
+          await app.close();
+     });
+});

package/tests/headers.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("custom response headers", () => {
+     it("sets custom headers on endpoint responses", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/data",
+                         response: { data: "value" },
+                         headers: {
+                              "X-Custom-Header": "test-value",
+                              "Cache-Control": "no-cache"
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/api/data" });
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["x-custom-header"]).toBe("test-value");
+          expect(res.headers["cache-control"]).toBe("no-cache");
+
+          await app.close();
+     });
+
+     it("supports template strings in header values", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/users/:id",
+                         response: { id: "{{params.id}}" },
+                         headers: {
+                              "X-User-ID": "{{params.id}}",
+                              "X-Query-Type": "{{query.type}}"
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/users/42?type=premium" });
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["x-user-id"]).toBe("42");
+          expect(res.headers["x-query-type"]).toBe("premium");
+
+          await app.close();
+     });
+
+     it("variant headers override endpoint headers", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/data",
+                         response: { source: "base" },
+                         headers: {
+                              "X-Source": "endpoint"
+                         },
+                         variants: [
+                              {
+                                   name: "special",
+                                   match: { query: { mode: "special" } },
+                                   response: { source: "variant" },
+                                   headers: {
+                                        "X-Source": "variant"
+                                   }
+                              }
+                         ]
+                    }
+               ]
+          });
+
+          const baseRes = await app.inject({ method: "GET", url: "/api/data" });
+          expect(baseRes.headers["x-source"]).toBe("endpoint");
+
+          const variantRes = await app.inject({ method: "GET", url: "/api/data?mode=special" });
+          expect(variantRes.headers["x-source"]).toBe("variant");
+
+          await app.close();
+     });
+
+     it("handles multiple custom headers", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/cors-test",
+                         response: { ok: true },
+                         headers: {
+                              "Access-Control-Allow-Origin": "*",
+                              "Access-Control-Allow-Methods": "GET, POST",
+                              "X-RateLimit-Limit": "100",
+                              "X-RateLimit-Remaining": "95"
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/api/cors-test" });
+          expect(res.headers["access-control-allow-origin"]).toBe("*");
+          expect(res.headers["access-control-allow-methods"]).toBe("GET, POST");
+          expect(res.headers["x-ratelimit-limit"]).toBe("100");
+          expect(res.headers["x-ratelimit-remaining"]).toBe("95");
+
+          await app.close();
+     });
+});

package/tests/helpers.ts

@@ -17,12 +17,12 @@ export async function loadFixture(path: string): Promise<MockSpecInferSchema> {
  */
 export async function buildTestServerFromFixture(path: string): Promise<FastifyInstance> {
      const spec = await loadFixture(path);
-     return buildServer(spec, { specPath: path, loadedAt: "now" });
+     return buildServer(spec, { specPath: path, loadedAt: "now", logger: false });
 }
 
 /**
  * Build a Fastify instance from an in-memory spec object.
  */
 export function buildTestServer(spec: MockSpecInferSchema): FastifyInstance {
-     return buildServer(spec, { specPath: "inline", loadedAt: "now" });
+     return buildServer(spec, { specPath: "inline", loadedAt: "now", logger: false });
 }

package/tests/history.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("request history", () => {
+     it("records all requests in history", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/test",
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          await app.inject({ method: "GET", url: "/api/test?foo=bar" });
+          await app.inject({ method: "GET", url: "/api/test?foo=baz" });
+
+          const historyRes = await app.inject({ method: "GET", url: "/__history" });
+          expect(historyRes.statusCode).toBe(200);
+
+          const history = historyRes.json();
+          expect(history.entries).toBeInstanceOf(Array);
+          expect(history.entries.length).toBeGreaterThanOrEqual(2);
+          expect(history.total).toBeGreaterThanOrEqual(2);
+
+          await app.close();
+     });
+
+     it("records request details including method, url, headers, and body", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/api/create",
+                         response: { id: 1 }
+                    }
+               ]
+          });
+
+          await app.inject({
+               method: "POST",
+               url: "/api/create",
+               headers: { "content-type": "application/json" },
+               payload: { name: "test" }
+          });
+
+          const historyRes = await app.inject({ method: "GET", url: "/__history?endpoint=/api/create" });
+          const history = historyRes.json();
+          
+          // Should have at least one POST to /api/create
+          const postEntries = history.entries.filter((e: {method: string; path: string}) => 
+               e.method === "POST" && e.path === "/api/create"
+          );
+          expect(postEntries.length).toBeGreaterThan(0);
+          
+          const lastEntry = postEntries[postEntries.length - 1];
+          expect(lastEntry.method).toBe("POST");
+          expect(lastEntry.url).toContain("/api/create");
+          expect(lastEntry.headers["content-type"]).toBe("application/json");
+          expect(lastEntry.body).toEqual({ name: "test" });
+
+          await app.close();
+     });
+
+     it("filters history by endpoint", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/users",
+                         response: { users: [] }
+                    },
+                    {
+                         method: "GET",
+                         path: "/api/posts",
+                         response: { posts: [] }
+                    }
+               ]
+          });
+
+          await app.inject({ method: "GET", url: "/api/users" });
+          await app.inject({ method: "GET", url: "/api/posts" });
+          await app.inject({ method: "GET", url: "/api/users" });
+
+          const historyRes = await app.inject({ method: "GET", url: "/__history?endpoint=/api/users" });
+          const history = historyRes.json();
+
+          expect(history.entries.every((e: { path: string }) => e.path === "/api/users")).toBe(true);
+
+          await app.close();
+     });
+
+     it("filters history by method", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/data",
+                         response: { data: "get" }
+                    },
+                    {
+                         method: "POST",
+                         path: "/api/data",
+                         response: { data: "post" }
+                    }
+               ]
+          });
+
+          await app.inject({ method: "GET", url: "/api/data" });
+          await app.inject({ method: "POST", url: "/api/data" });
+          await app.inject({ method: "GET", url: "/api/data" });
+
+          const historyRes = await app.inject({ method: "GET", url: "/__history?method=POST" });
+          const history = historyRes.json();
+
+          expect(history.entries.every((e: { method: string }) => e.method === "POST")).toBe(true);
+
+          await app.close();
+     });
+
+     it("clears history on DELETE request", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/test",
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          await app.inject({ method: "GET", url: "/api/test" });
+
+          const beforeClear = await app.inject({ method: "GET", url: "/__history" });
+          expect(beforeClear.json().entries.length).toBeGreaterThan(0);
+
+          await app.inject({ method: "DELETE", url: "/__history" });
+
+          const afterClear = await app.inject({ method: "GET", url: "/__history" });
+          // Should only have the history requests themselves
+          expect(afterClear.json().entries.length).toBeLessThanOrEqual(2);
+
+          await app.close();
+     });
+
+     it("limits history entries with limit parameter", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/api/test",
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          for (let i = 0; i < 10; i++) {
+               await app.inject({ method: "GET", url: "/api/test" });
+          }
+
+          const historyRes = await app.inject({ method: "GET", url: "/__history?limit=3" });
+          const history = historyRes.json();
+
+          expect(history.entries.length).toBeLessThanOrEqual(3);
+
+          await app.close();
+     });
+});