api-json-server 1.1.0 → 1.2.0

package/src/behavior.ts

@@ -1,4 +1,7 @@
 import type { TemplateValue } from "./spec.js";
+import { faker } from "@faker-js/faker";
+
+export type DelayConfig = number | { min: number; max: number };
 
 export type BehaviorSettings = {
      delayMs: number;
@@ -7,7 +10,18 @@ export type BehaviorSettings = {
      errorResponse: TemplateValue;
 };
 
-export type BehaviorOverrides = Partial<BehaviorSettings>;
+export type BehaviorOverrides = Partial<BehaviorSettings> & {
+     delay?: DelayConfig;
+};
+
+/**
+ * Resolve a delay value from either a number or a range configuration.
+ */
+export function resolveDelay(delay?: DelayConfig): number {
+     if (!delay) return 0;
+     if (typeof delay === "number") return delay;
+     return faker.number.int({ min: delay.min, max: delay.max });
+}
 
 /**
  * Pause for the given number of milliseconds.

package/src/history/historyRecorder.ts

@@ -0,0 +1,77 @@
+import type { HistoryEntry, HistoryFilter } from "./types.js";
+import { randomUUID } from "node:crypto";
+
+/**
+ * In-memory request history recorder.
+ */
+export class HistoryRecorder {
+     private entries: HistoryEntry[] = [];
+     private readonly maxEntries: number;
+
+     /**
+      * Create a new history recorder.
+      * @param maxEntries Maximum number of entries to keep (default 1000).
+      */
+     constructor(maxEntries = 1000) {
+          this.maxEntries = maxEntries;
+     }
+
+     /**
+      * Record a new request.
+      */
+     record(entry: Omit<HistoryEntry, "id" | "timestamp">): HistoryEntry {
+          const fullEntry: HistoryEntry = {
+               id: randomUUID(),
+               timestamp: new Date().toISOString(),
+               ...entry
+          };
+
+          this.entries.push(fullEntry);
+
+          // Keep only the most recent entries
+          if (this.entries.length > this.maxEntries) {
+               this.entries.shift();
+          }
+
+          return fullEntry;
+     }
+
+     /**
+      * Get all history entries, optionally filtered.
+      */
+     query(filter?: HistoryFilter): HistoryEntry[] {
+          let results = this.entries;
+
+          if (filter?.endpoint) {
+               results = results.filter((e) => e.path === filter.endpoint);
+          }
+
+          if (filter?.method) {
+               results = results.filter((e) => e.method.toUpperCase() === filter.method?.toUpperCase());
+          }
+
+          if (filter?.statusCode !== undefined) {
+               results = results.filter((e) => e.statusCode === filter.statusCode);
+          }
+
+          if (filter?.limit && filter.limit > 0) {
+               results = results.slice(-filter.limit);
+          }
+
+          return results;
+     }
+
+     /**
+      * Clear all history entries.
+      */
+     clear(): void {
+          this.entries = [];
+     }
+
+     /**
+      * Get the total number of recorded entries.
+      */
+     count(): number {
+          return this.entries.length;
+     }
+}

package/src/history/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Request history entry structure.
+ */
+export interface HistoryEntry {
+     id: string;
+     timestamp: string;
+     method: string;
+     url: string;
+     path: string;
+     query: Record<string, unknown>;
+     headers: Record<string, string | string[] | undefined>;
+     body: unknown;
+     statusCode?: number;
+     responseTime?: number;
+}
+
+/**
+ * Filter options for querying history.
+ */
+export interface HistoryFilter {
+     endpoint?: string;
+     method?: string;
+     statusCode?: number;
+     limit?: number;
+}

package/src/index.ts

@@ -2,6 +2,8 @@
 
 import { Command } from "commander";
 import { watch } from "node:fs";
+import { createLogger, logServerStart, logServerReload } from "./logger/customLogger.js";
+import type { LoggerOptions } from "./logger/types.js";
 
 const program = new Command();
 
@@ -18,14 +20,16 @@ program
      .option("--watch", "Reload when spec file changes", true)
      .option("--no-watch", "Disable reload when spec file changes")
      .option("--base-url <url>", "Public base URL used in OpenAPI servers[] (e.g. https://example.com)")
-     .action(async (opts: { port: string; spec: string; watch: boolean; baseUrl?: string }) => {
+     .option("--log-format <format>", "Log format: pretty or json", "pretty")
+     .option("--log-level <level>", "Log level: trace, debug, info, warn, error, fatal", "info")
+     .action(async (opts: { port: string; spec: string; watch: boolean; baseUrl?: string; logFormat: string; logLevel: string }) => {
           await startCommand(opts);
      });
 
 /**
  * Run the mock server CLI command.
  */
-async function startCommand(opts: { port: string; spec: string; watch: boolean; baseUrl?: string }): Promise<void> {
+async function startCommand(opts: { port: string; spec: string; watch: boolean; baseUrl?: string; logFormat: string; logLevel: string }): Promise<void> {
      const port = Number(opts.port);
 
      if (!Number.isFinite(port) || port <= 0) {
@@ -35,6 +39,18 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
 
      const specPath = opts.spec;
 
+     // Create logger based on CLI options
+     const logFormat = opts.logFormat === "json" ? "json" : "pretty";
+     const logLevel = ["trace", "debug", "info", "warn", "error", "fatal"].includes(opts.logLevel)
+          ? opts.logLevel as LoggerOptions["level"]
+          : "info";
+
+     const logger = createLogger({
+          enabled: true,
+          format: logFormat,
+          level: logLevel
+     });
+
      const { loadSpecFromFile } = await import("./loadSpec.js");
      const { buildServer } = await import("./server.js");
 
@@ -49,9 +65,9 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
           const loadedAt = new Date().toISOString();
 
           const spec = await loadSpecFromFile(specPath);
-          console.log(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
+          logger.info(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
 
-          const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl });
+          const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl, logger: true });
           try {
                await nextApp.listen({ port, host: "0.0.0.0" });
           } catch (err) {
@@ -59,8 +75,7 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
                throw err;
           }
 
-          nextApp.log.info(`Mock server running on http://localhost:${port}`);
-          nextApp.log.info(`Spec: ${specPath} (loadedAt=${loadedAt})`);
+          logServerStart(nextApp.log, port, specPath);
 
           return nextApp;
      }
@@ -73,36 +88,34 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
           isReloading = true;
 
           try {
-               console.log("Reloading spec...");
+               logger.info("Reloading spec...");
 
                // 1) Stop accepting requests on the old server FIRST
                if (app) {
-                    console.log("Closing current server...");
+                    logger.debug("Closing current server...");
                     await app.close();
-                    console.log("Current server closed.");
+                    logger.debug("Current server closed.");
                     app = null;
                }
 
                // 2) Start a new server on the same port with the updated spec
                app = await startWithSpec();
 
-               console.log("Reload complete.");
+               logServerReload(logger, true);
           } catch (err) {
-               console.error("Reload failed.");
-
-               // At this point the old server may already be closed. We want visibility.
-               console.error(String(err));
+               const errorMsg = err instanceof Error ? err.message : String(err);
+               logServerReload(logger, false, errorMsg);
 
                // Optional: try to start again to avoid being down
                try {
                     if (!app) {
-                         console.log("Attempting to start server again after reload failure...");
+                         logger.info("Attempting to start server again after reload failure...");
                          app = await startWithSpec();
-                         console.log("Recovery start succeeded.");
+                         logger.info("Recovery start succeeded.");
                     }
                } catch (err2) {
-                    console.error("Recovery start failed. Server is down until next successful reload.");
-                    console.error(String(err2));
+                    logger.error("Recovery start failed. Server is down until next successful reload.");
+                    logger.error(err2);
                }
           } finally {
                isReloading = false;
@@ -113,7 +126,7 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
      try {
           app = await startWithSpec();
      } catch (err) {
-          console.error(String(err));
+          logger.error(err);
           process.exit(1);
      }
 
@@ -126,12 +139,12 @@ async function startCommand(opts: { port: string; spec: string; watch: boolean;
      }
 
      if (opts.watch) {
-          console.log(`Watching spec file for changes: ${specPath}`);
+          logger.info(`Watching spec file for changes: ${specPath}`);
 
           // fs.watch emits multiple events; debounce to avoid rapid reload loops
           watch(specPath, onSpecChange);
      } else {
-          console.log("Watch disabled (--no-watch).");
+          logger.info("Watch disabled (--no-watch).");
      }
 }
 

package/src/logger/customLogger.ts

@@ -0,0 +1,85 @@
+import type { FastifyBaseLogger } from "fastify";
+import pino from "pino";
+import type { LoggerOptions } from "./types.js";
+import { formatStatusCode, formatMethod, formatResponseTime, formatTimestamp, formatLogLevel } from "./formatters.js";
+
+/**
+ * Create a custom logger for the mock server.
+ */
+export function createLogger(options: LoggerOptions): FastifyBaseLogger {
+     if (!options.enabled) {
+          return pino({ level: "silent" });
+     }
+
+     if (options.format === "json") {
+          return pino({
+               level: options.level,
+               timestamp: pino.stdTimeFunctions.isoTime
+          });
+     }
+
+     // Pretty format with custom output (simplified to avoid serialization issues in tests)
+     return pino({
+          level: options.level,
+          transport: {
+               target: "pino-pretty",
+               options: {
+                    colorize: true,
+                    translateTime: "HH:MM:ss",
+                    ignore: "pid,hostname",
+                    messageFormat: "{msg}"
+               }
+          }
+     });
+}
+
+/**
+ * Format and log a request/response pair.
+ */
+export function logRequest(
+     logger: FastifyBaseLogger,
+     method: string,
+     url: string,
+     statusCode: number,
+     responseTime: number
+): void {
+     const formattedMethod = formatMethod(method);
+     const formattedStatus = formatStatusCode(statusCode);
+     const formattedTime = formatResponseTime(responseTime);
+
+     logger.info(`${formattedMethod} ${url} ${formattedStatus} ${formattedTime}`);
+}
+
+/**
+ * Log server startup.
+ */
+export function logServerStart(logger: FastifyBaseLogger, port: number, specPath: string): void {
+     logger.info(`🚀 Mock server running on http://localhost:${port}`);
+     logger.info(`📄 Spec: ${specPath}`);
+     logger.info(`📖 Docs: http://localhost:${port}/docs`);
+}
+
+/**
+ * Log server reload.
+ */
+export function logServerReload(logger: FastifyBaseLogger, success: boolean, error?: string): void {
+     if (success) {
+          logger.info("✅ Spec reloaded successfully");
+     } else {
+          logger.error(`❌ Reload failed: ${error}`);
+     }
+}
+
+/**
+ * Log endpoint registration.
+ */
+export function logEndpointRegistered(
+     logger: FastifyBaseLogger,
+     method: string,
+     path: string,
+     status?: number
+): void {
+     const formattedMethod = formatMethod(method);
+     const statusInfo = status ? ` → ${status}` : "";
+     logger.debug(`Registered ${formattedMethod} ${path}${statusInfo}`);
+}

package/src/logger/formatters.ts

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+
+/**
+ * Format HTTP status code with color based on status range.
+ */
+export function formatStatusCode(statusCode: number): string {
+     if (statusCode >= 500) {
+          return chalk.red(statusCode.toString());
+     }
+     if (statusCode >= 400) {
+          return chalk.yellow(statusCode.toString());
+     }
+     if (statusCode >= 300) {
+          return chalk.cyan(statusCode.toString());
+     }
+     if (statusCode >= 200) {
+          return chalk.green(statusCode.toString());
+     }
+     return chalk.white(statusCode.toString());
+}
+
+/**
+ * Format HTTP method with color.
+ */
+export function formatMethod(method: string): string {
+     const colors: Record<string, (str: string) => string> = {
+          GET: chalk.green,
+          POST: chalk.blue,
+          PUT: chalk.yellow,
+          PATCH: chalk.magenta,
+          DELETE: chalk.red,
+          HEAD: chalk.gray,
+          OPTIONS: chalk.cyan
+     };
+     const formatter = colors[method.toUpperCase()] || chalk.white;
+     return formatter(method.toUpperCase().padEnd(7));
+}
+
+/**
+ * Format response time with color based on duration.
+ */
+export function formatResponseTime(ms: number): string {
+     const formatted = `${ms.toFixed(2)}ms`;
+     if (ms > 1000) return chalk.red(formatted);
+     if (ms > 500) return chalk.yellow(formatted);
+     if (ms > 100) return chalk.cyan(formatted);
+     return chalk.green(formatted);
+}
+
+/**
+ * Format timestamp in readable format.
+ */
+export function formatTimestamp(date: Date): string {
+     const hours = date.getHours().toString().padStart(2, "0");
+     const minutes = date.getMinutes().toString().padStart(2, "0");
+     const seconds = date.getSeconds().toString().padStart(2, "0");
+     return chalk.gray(`[${hours}:${minutes}:${seconds}]`);
+}
+
+/**
+ * Format a log level with appropriate color.
+ */
+export function formatLogLevel(level: string): string {
+     const colors: Record<string, (str: string) => string> = {
+          trace: chalk.gray,
+          debug: chalk.cyan,
+          info: chalk.blue,
+          warn: chalk.yellow,
+          error: chalk.red,
+          fatal: chalk.bgRed.white
+     };
+     const formatter = colors[level.toLowerCase()] || chalk.white;
+     return formatter(level.toUpperCase().padEnd(5));
+}

package/src/logger/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Logger configuration options.
+ */
+export interface LoggerOptions {
+     /**
+      * Enable/disable logging.
+      */
+     enabled: boolean;
+
+     /**
+      * Log format: 'pretty' for colored console output, 'json' for structured logs.
+      */
+     format: "pretty" | "json";
+
+     /**
+      * Log level: 'trace', 'debug', 'info', 'warn', 'error', 'fatal'.
+      */
+     level: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+}
+
+/**
+ * Request log entry structure.
+ */
+export interface RequestLogEntry {
+     method: string;
+     url: string;
+     statusCode: number;
+     responseTime: number;
+     timestamp: string;
+}

package/src/registerEndpoints.ts

@@ -2,11 +2,14 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import type { MockSpecInferSchema, EndpointSpecInferSchema, TemplateValue } from "./spec.js";
 import { matchRequest, toRecord } from "./requestMatch.js";
 import { createRenderContext, renderTemplateValue } from "./responseRenderer.js";
-import { resolveBehavior, shouldFail, sleep, type BehaviorOverrides } from "./behavior.js";
+import { resolveBehavior, shouldFail, sleep, resolveDelay, type BehaviorOverrides, type DelayConfig } from "./behavior.js";
+import { logEndpointRegistered } from "./logger/customLogger.js";
 
 type ResponseSource = {
      status?: number;
      response: TemplateValue;
+     headers?: Record<string, string>;
+     delay?: DelayConfig;
 } & BehaviorOverrides;
 
 /**
@@ -19,6 +22,8 @@ function selectVariant(req: FastifyRequest, endpoint: EndpointSpecInferSchema):
                return {
                     status: variant.status,
                     response: variant.response,
+                    headers: variant.headers,
+                    delay: variant.delay,
                     delayMs: variant.delayMs,
                     errorRate: variant.errorRate,
                     errorStatus: variant.errorStatus,
@@ -36,6 +41,8 @@ function selectEndpointSource(endpoint: EndpointSpecInferSchema): ResponseSource
      return {
           status: endpoint.status,
           response: endpoint.response,
+          headers: endpoint.headers,
+          delay: endpoint.delay,
           delayMs: endpoint.delayMs,
           errorRate: endpoint.errorRate,
           errorStatus: endpoint.errorStatus,
@@ -54,9 +61,7 @@ export function registerEndpoints(app: FastifyInstance, spec: MockSpecInferSchem
                handler: buildEndpointHandler(spec, endpoint)
           });
 
-          app.log.info(
-               `Registered ${endpoint.method} ${endpoint.path} -> ${endpoint.status} (delay=${endpoint.delayMs ?? spec.settings.delayMs}ms, errorRate=${endpoint.errorRate ?? spec.settings.errorRate})`
-          );
+          logEndpointRegistered(app.log, endpoint.method, endpoint.path, endpoint.status);
      }
 }
 
@@ -75,8 +80,10 @@ function buildEndpointHandler(spec: MockSpecInferSchema, endpoint: EndpointSpecI
           const source = variant ?? selectEndpointSource(endpoint);
           const behavior = resolveBehavior(spec.settings, endpoint, source);
 
-          if (behavior.delayMs > 0) {
-               await sleep(behavior.delayMs);
+          // Resolve delay (supports both delay and delayMs, with delay taking precedence)
+          const delayValue = source.delay ? resolveDelay(source.delay) : behavior.delayMs;
+          if (delayValue > 0) {
+               await sleep(delayValue);
           }
 
           const params = toRecord(req.params);
@@ -89,6 +96,17 @@ function buildEndpointHandler(spec: MockSpecInferSchema, endpoint: EndpointSpecI
                return renderTemplateValue(behavior.errorResponse, renderContext);
           }
 
+          // Apply custom headers (with template support)
+          const headers = source.headers ?? endpoint.headers;
+          if (headers) {
+               for (const [key, value] of Object.entries(headers)) {
+                    const renderedValue = typeof value === "string" 
+                         ? String(renderTemplateValue(value, renderContext))
+                         : String(value);
+                    reply.header(key, renderedValue);
+               }
+          }
+
           const rendered = renderTemplateValue(source.response, renderContext);
 
           reply.code(source.status ?? endpoint.status ?? 200);

package/src/requestMatch.ts

@@ -4,6 +4,8 @@ import type { Primitive } from "./spec.js";
 export type MatchRule = {
      query?: Record<string, Primitive>;
      body?: Record<string, Primitive>;
+     headers?: Record<string, string>;
+     cookies?: Record<string, string>;
 };
 
 /**
@@ -52,11 +54,51 @@ function bodyMatches(req: FastifyRequest, expected?: Record<string, Primitive>):
 }
 
 /**
- * Check if a request matches query/body rules.
+ * Check if the request headers match the expected values (case-insensitive).
+ */
+function headersMatch(req: FastifyRequest, expected?: Record<string, string>): boolean {
+     if (!expected) return true;
+
+     // Normalize header keys to lowercase for case-insensitive matching
+     const headers = new Map<string, string>();
+     for (const [key, value] of Object.entries(req.headers)) {
+          if (typeof value === "string") {
+               headers.set(key.toLowerCase(), value);
+          }
+     }
+
+     for (const [key, exp] of Object.entries(expected)) {
+          const actual = headers.get(key.toLowerCase());
+          if (actual !== exp) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if the request cookies match the expected values.
+ */
+function cookiesMatch(req: FastifyRequest, expected?: Record<string, string>): boolean {
+     if (!expected) return true;
+
+     const cookies = (req as FastifyRequest & { cookies?: Record<string, string> }).cookies;
+     if (!cookies) return false;
+
+     for (const [key, exp] of Object.entries(expected)) {
+          if (cookies[key] !== exp) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if a request matches query/body/headers/cookies rules.
  */
 export function matchRequest(req: FastifyRequest, match?: MatchRule): boolean {
      if (!match) return true;
      if (!queryMatches(req, match.query)) return false;
      if (!bodyMatches(req, match.body)) return false;
+     if (!headersMatch(req, match.headers)) return false;
+     if (!cookiesMatch(req, match.cookies)) return false;
      return true;
 }