llm-mock-server 1.0.0

package/src/route-handler.ts

@@ -0,0 +1,113 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { ZodError } from "zod";
+import type { Reply, ReplyObject, ReplyOptions, MockRequest, Rule } from "./types.js";
+import type { Format } from "./formats/types.js";
+import type { RuleEngine } from "./rule-engine.js";
+import type { RequestHistory } from "./history.js";
+import type { Logger } from "./logger.js";
+import { writeSSE } from "./sse-writer.js";
+
+const HTTP_BAD_REQUEST = 400;
+
+function normalizeReply(reply: Reply): ReplyObject {
+  if (typeof reply === "string") return { text: reply };
+  return reply;
+}
+
+async function resolveReply(
+  matched: Rule | undefined,
+  mockReq: MockRequest,
+  fallback: Reply,
+  logger: Logger,
+): Promise<{ reply: ReplyObject; ruleDesc: string | undefined }> {
+  if (!matched) {
+    logger.warn(`No matching rule for "${mockReq.lastMessage}", using fallback`);
+    return { reply: normalizeReply(fallback), ruleDesc: undefined };
+  }
+
+  try {
+    const raw = typeof matched.resolve === "function"
+      ? await matched.resolve(mockReq)
+      : matched.resolve;
+    logger.debug(`Matched rule ${matched.description}`);
+    return { reply: normalizeReply(raw), ruleDesc: matched.description };
+  } catch (err) {
+    logger.error(`Resolver threw for rule ${matched.description}`, err);
+    return { reply: normalizeReply(fallback), ruleDesc: matched.description };
+  }
+}
+
+export interface RouteHandlerDeps {
+  engine: RuleEngine;
+  history: RequestHistory;
+  logger: Logger;
+  defaultOptions: ReplyOptions;
+  getFallback: () => Reply;
+}
+
+export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
+  const { engine, history, logger, defaultOptions, getFallback } = deps;
+
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = request.body;
+    const headers: Record<string, string | undefined> = {};
+    for (const [key, val] of Object.entries(request.headers)) {
+      headers[key] = Array.isArray(val) ? val.join(", ") : val;
+    }
+    const meta = { headers, path: request.url };
+
+    let mockReq: MockRequest;
+    try {
+      mockReq = format.parseRequest(body, meta);
+    } catch (err) {
+      if (err instanceof ZodError) {
+        logger.warn(`Invalid ${format.name} request: ${err.issues.map((i) => i.message).join(", ")}`);
+        return reply.status(HTTP_BAD_REQUEST).type("application/json").send(
+          format.serializeError({ status: HTTP_BAD_REQUEST, message: "Invalid request body", type: "invalid_request_error" }),
+        );
+      }
+      throw err;
+    }
+    const startTime = Date.now();
+
+    logger.debug(
+      `${format.name} request: model=${mockReq.model} streaming=${mockReq.streaming} messages=${mockReq.messages.length}`,
+    );
+
+    const matched = engine.match(mockReq);
+    const { reply: resolvedReply, ruleDesc } = await resolveReply(
+      matched, mockReq, getFallback(), logger,
+    );
+
+    if (resolvedReply.error) {
+      const { error } = resolvedReply;
+      logger.info(`Error reply: ${String(error.status)} ${error.message}`);
+      history.record(mockReq, ruleDesc);
+      return reply.status(error.status).type("application/json").send(format.serializeError(error));
+    }
+
+    history.record(mockReq, ruleDesc);
+
+    const isStreaming = format.isStreaming(body);
+    const effectiveOptions = { ...defaultOptions, ...matched?.options };
+    const elapsed = Date.now() - startTime;
+    const mode = isStreaming ? "stream" : "json";
+
+    logger.info(
+      `POST ${format.route} [${mode}] "${mockReq.lastMessage}" -> ${ruleDesc ?? "fallback"} (${elapsed}ms)`,
+    );
+    if (resolvedReply.text) {
+      logger.debug(`Reply text: "${resolvedReply.text}"`);
+    }
+    if (resolvedReply.tools?.length) {
+      logger.debug(`Reply tool calls: ${resolvedReply.tools.map((t) => t.name).join(", ")}`);
+    }
+
+    if (!isStreaming) {
+      return reply.type("application/json").send(format.serializeComplete(resolvedReply, mockReq.model));
+    }
+
+    const chunks = format.serialize(resolvedReply, mockReq.model, effectiveOptions);
+    await writeSSE(reply, chunks, effectiveOptions);
+  };
+}

package/src/rule-engine.ts

@@ -0,0 +1,119 @@
+import type { Match, MatchObject, MockRequest, Resolver, ReplyOptions, Rule, RuleSummary } from "./types.js";
+
+function safeRegex(re: RegExp): RegExp {
+  return (re.global || re.sticky) ? new RegExp(re.source, re.flags.replace(/[gy]/g, "")) : re;
+}
+
+function compilePattern(pattern: string | RegExp): (value: string) => boolean {
+  if (typeof pattern === "string") {
+    const lower = pattern.toLowerCase();
+    return (value) => value.toLowerCase().includes(lower);
+  }
+  const re = safeRegex(pattern);
+  return (value) => re.test(value);
+}
+
+function compileMatcher(match: Match): (req: MockRequest) => boolean {
+  if (typeof match === "string") {
+    const test = compilePattern(match);
+    return (req) => test(req.lastMessage);
+  }
+  if (match instanceof RegExp) {
+    const test = compilePattern(match);
+    return (req) => test(req.lastMessage);
+  }
+  if (typeof match === "function") {
+    return match;
+  }
+  const obj = match;
+  const messageTest = obj.message !== undefined ? compilePattern(obj.message) : undefined;
+  const modelTest = obj.model !== undefined ? compilePattern(obj.model) : undefined;
+  const systemTest = obj.system !== undefined ? compilePattern(obj.system) : undefined;
+  return (req) => {
+    if (messageTest && !messageTest(req.lastMessage)) return false;
+    if (modelTest && !modelTest(req.model)) return false;
+    if (systemTest && !systemTest(req.systemMessage)) return false;
+    if (obj.format !== undefined && req.format !== obj.format) return false;
+    if (obj.toolName !== undefined && !req.toolNames.includes(obj.toolName)) return false;
+    if (obj.toolCallId !== undefined && req.lastToolCallId !== obj.toolCallId) return false;
+    if (obj.predicate && !obj.predicate(req)) return false;
+    return true;
+  };
+}
+
+function describeMatch(match: Match): string {
+  if (typeof match === "string") return `"${match}"`;
+  if (match instanceof RegExp) return match.toString();
+  if (typeof match === "function") return "(predicate)";
+  const obj: MatchObject = match;
+  const parts = Object.entries(obj)
+    .filter(([, v]) => v !== undefined && typeof v !== "function")
+    .map(([k, v]) => `${k}=${String(v)}`);
+  return `{${parts.join(", ")}}`;
+}
+
+function createRule(match: Match, resolve: Resolver, options: ReplyOptions, description?: string): Rule {
+  return {
+    description: description ?? describeMatch(match),
+    match: compileMatcher(match),
+    resolve,
+    options,
+    remaining: Infinity,
+  };
+}
+
+export class RuleEngine {
+  private readonly rules: Rule[] = [];
+
+  add(match: Match, resolve: Resolver, options: ReplyOptions = {}): Rule {
+    const rule = createRule(match, resolve, options);
+    this.rules.push(rule);
+    return rule;
+  }
+
+  moveToFront(rule: Rule): void {
+    const idx = this.rules.indexOf(rule);
+    if (idx > 0) {
+      this.rules.splice(idx, 1);
+      this.rules.unshift(rule);
+    }
+  }
+
+  addHandler(matchFn: (req: MockRequest) => boolean, respond: Resolver, description = "(handler)"): Rule {
+    const rule = createRule(matchFn, respond, {}, description);
+    this.rules.push(rule);
+    return rule;
+  }
+
+  match(req: MockRequest): Rule | undefined {
+    for (let i = 0; i < this.rules.length; i++) {
+      const rule = this.rules[i]!;
+
+      if (rule.remaining <= 0) continue;
+      if (!rule.match(req)) continue;
+
+      rule.remaining--;
+      if (rule.remaining <= 0) {
+        this.rules.splice(i, 1);
+      }
+      return rule;
+    }
+    return undefined;
+  }
+
+  isDone(): boolean {
+    return this.rules.every((r) => !Number.isFinite(r.remaining) || r.remaining <= 0);
+  }
+
+  get ruleCount(): number {
+    return this.rules.length;
+  }
+
+  describe(): readonly RuleSummary[] {
+    return this.rules.map((r) => ({ description: r.description, remaining: r.remaining }));
+  }
+
+  clear(): void {
+    this.rules.length = 0;
+  }
+}

package/src/sse-writer.ts

@@ -0,0 +1,35 @@
+import type { FastifyReply } from "fastify";
+import type { SSEChunk } from "./formats/types.js";
+import type { ReplyOptions } from "./types.js";
+
+const HTTP_OK = 200;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function formatSSEChunk(chunk: SSEChunk): string {
+  const eventLine = chunk.event ? `event: ${chunk.event}\n` : "";
+  return `${eventLine}data: ${chunk.data}\n\n`;
+}
+
+export async function writeSSE(
+  reply: FastifyReply,
+  chunks: readonly SSEChunk[],
+  options: ReplyOptions = {},
+): Promise<void> {
+  const latency = options.latency ?? 0;
+
+  reply.raw.writeHead(HTTP_OK, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+
+  for (const chunk of chunks) {
+    reply.raw.write(formatSSEChunk(chunk));
+    if (latency > 0) await sleep(latency);
+  }
+
+  reply.raw.end();
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export type { FormatName, MockRequest, Message, ToolDef } from "./request.js";
+export type { Reply, ReplyObject, ErrorReply, ToolCall, Resolver, ReplyOptions, SequenceEntry } from "./reply.js";
+export type { Match, MatchObject, PendingRule, RuleHandle, RuleSummary, Handler, Rule } from "./rule.js";
+export type { RecordedRequest } from "../history.js";

package/src/types/reply.ts

@@ -0,0 +1,49 @@
+import type { MockRequest } from "./request.js";
+
+/** A reply is either a plain string (turns into `{ text: "..." }`) or a full reply object. */
+export type Reply = string | ReplyObject;
+
+/** A structured reply. Text, reasoning, tool calls, usage, and errors are all optional. */
+export interface ReplyObject {
+  /** Text content to send back. */
+  readonly text?: string | undefined;
+  /** Extended thinking or chain-of-thought. Works with Anthropic and Responses formats. */
+  readonly reasoning?: string | undefined;
+  /** Tool calls the "model" wants to make. */
+  readonly tools?: readonly ToolCall[] | undefined;
+  /** Token counts to report. Falls back to `{ input: 10, output: 5 }` if omitted. */
+  readonly usage?: { readonly input: number; readonly output: number } | undefined;
+  /** When set, the server responds with this HTTP error instead of a normal reply. */
+  readonly error?: ErrorReply | undefined;
+}
+
+/** An HTTP error response. The server returns this status code with a format-appropriate body. */
+export interface ErrorReply {
+  /** HTTP status code, like 429 or 500. */
+  readonly status: number;
+  readonly message: string;
+  /** Error type string in the response body. Each format has its own default if omitted. */
+  readonly type?: string | undefined;
+}
+
+/** A tool call in the mock response. */
+export interface ToolCall {
+  /** Explicit ID for the call. Auto-generated if omitted. */
+  readonly id?: string | undefined;
+  readonly name: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+
+/** A reply value or a function that produces one. Async functions are supported. */
+export type Resolver = Reply | ((req: MockRequest) => Reply | Promise<Reply>);
+
+/** Streaming options for a rule. Merged with server-level defaults, with per-rule values winning. */
+export interface ReplyOptions {
+  /** Milliseconds to wait between SSE chunks. */
+  readonly latency?: number | undefined;
+  /** Split text into chunks of this many characters for more realistic streaming. */
+  readonly chunkSize?: number | undefined;
+}
+
+/** A single entry in a reply sequence. Can be a plain reply or a reply with per-step options. */
+export type SequenceEntry = Reply | { readonly reply: Reply; readonly options?: ReplyOptions };

package/src/types/request.ts

@@ -0,0 +1,45 @@
+/** The LLM API wire format that was detected for a request. */
+export type FormatName = "openai" | "anthropic" | "responses";
+
+/** A normalised view of an incoming request, regardless of the original wire format. */
+export interface MockRequest {
+  /** Which format route the request hit. */
+  readonly format: FormatName;
+  readonly model: string;
+  /** Whether the client asked for SSE streaming. */
+  readonly streaming: boolean;
+  /** Full conversation, normalised from whatever format came in. */
+  readonly messages: readonly Message[];
+  /** The last user message's text. This is what most matchers check. */
+  readonly lastMessage: string;
+  /** System prompt text, or `""` if there wasn't one. */
+  readonly systemMessage: string;
+  /** Tool definitions from the request, if any were sent. */
+  readonly tools?: readonly ToolDef[] | undefined;
+  /** The names from `tools`, pulled out for quick lookups. */
+  readonly toolNames: readonly string[];
+  /** If the last message was a tool result, this is its `tool_call_id`. */
+  readonly lastToolCallId: string | undefined;
+  /** The raw request body, in case you need something we don't extract. */
+  readonly raw: unknown;
+  /** HTTP headers from the incoming request. */
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  /** The URL path that was hit, e.g. `/v1/chat/completions`. */
+  readonly path: string;
+}
+
+/** A single conversation message, normalised across all supported formats. */
+export interface Message {
+  readonly role: "system" | "user" | "assistant" | "tool";
+  readonly content: string;
+  /** Only set on `"tool"` messages. Links the result back to its tool call. */
+  readonly toolCallId?: string | undefined;
+}
+
+/** A tool definition from the request's `tools` array, normalised across formats. */
+export interface ToolDef {
+  readonly name: string;
+  readonly description?: string | undefined;
+  /** JSON Schema for the tool's parameters, passed through as-is. */
+  readonly parameters?: unknown;
+}

package/src/types/rule.ts

@@ -0,0 +1,74 @@
+import type { MockRequest, FormatName } from "./request.js";
+import type { Resolver, ReplyOptions, Reply, SequenceEntry } from "./reply.js";
+
+/**
+ * Determines whether a rule matches an incoming request.
+ *
+ * A `string` does a case-insensitive substring match on the last user message.
+ * A `RegExp` gets tested against the last user message.
+ * A `MatchObject` checks multiple fields at once with AND logic.
+ * A function receives the normalised request and returns a boolean.
+ */
+export type Match =
+  | string
+  | RegExp
+  | MatchObject
+  | ((req: MockRequest) => boolean);
+
+/** A structured matcher. Every field you set must match for the rule to fire. */
+export interface MatchObject {
+  /** Substring or regex against the last user message. */
+  readonly message?: string | RegExp;
+  /** Substring or regex against the model name. */
+  readonly model?: string | RegExp;
+  /** Substring or regex against the system prompt. */
+  readonly system?: string | RegExp;
+  /** Only match requests from this API format. */
+  readonly format?: FormatName;
+  /** Match when the request includes a tool definition with this name. */
+  readonly toolName?: string;
+  /** Match when the last tool-result message has this `tool_call_id`. */
+  readonly toolCallId?: string;
+  /** Extra check that runs after all other fields pass. */
+  readonly predicate?: (req: MockRequest) => boolean;
+}
+
+/** Returned by `when()`. Call `.reply()` or `.replySequence()` on it to complete the rule. */
+export interface PendingRule {
+  reply(response: Resolver, options?: ReplyOptions): RuleHandle;
+  /** Each match advances through the array. The last entry repeats once the sequence is exhausted. */
+  replySequence(entries: readonly SequenceEntry[]): RuleHandle;
+}
+
+/** A handle to a registered rule. All methods return `this` for chaining. */
+export interface RuleHandle {
+  /** Auto-expire the rule after `n` matches. */
+  times(n: number): RuleHandle;
+  /** Move this rule to the front of the list so it matches first. */
+  first(): RuleHandle;
+}
+
+/**
+ * The shape of a handler file's default export.
+ * You can export a single handler or an array of them.
+ */
+export interface Handler {
+  match: (req: MockRequest) => boolean;
+  respond: (req: MockRequest) => Reply | Promise<Reply>;
+}
+
+/** A summary of a registered rule, for inspection. */
+export interface RuleSummary {
+  /** Human-readable description of what the rule matches. */
+  readonly description: string;
+  /** How many matches are left. `Infinity` means unlimited. */
+  readonly remaining: number;
+}
+
+export interface Rule {
+  readonly description: string;
+  readonly match: (req: MockRequest) => boolean;
+  readonly resolve: Resolver;
+  options: ReplyOptions;
+  remaining: number;
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+export type {
+  FormatName, MockRequest, Message, ToolDef,
+  Reply, ReplyObject, ErrorReply, ToolCall, Resolver, ReplyOptions, SequenceEntry,
+  Match, MatchObject, PendingRule, RuleHandle, RuleSummary, Handler, RecordedRequest, Rule,
+} from "./types/index.js";

package/test/cli-validators.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { parsePort, parseHost, parseChunkSize, parseLogLevel, parseLatency } from "../src/cli-validators.js";
+
+describe("parsePort", () => {
+  it("parses a valid port", () => {
+    expect(parsePort("5555")).toBe(5555);
+  });
+
+  it("accepts port 1", () => {
+    expect(parsePort("1")).toBe(1);
+  });
+
+  it("accepts port 65535", () => {
+    expect(parsePort("65535")).toBe(65535);
+  });
+
+  it("throws on port 0", () => {
+    expect(() => parsePort("0")).toThrow('Invalid port "0"');
+  });
+
+  it("throws on port above 65535", () => {
+    expect(() => parsePort("65536")).toThrow('Invalid port "65536"');
+  });
+
+  it("throws on negative port", () => {
+    expect(() => parsePort("-1")).toThrow('Invalid port "-1"');
+  });
+
+  it("throws on non-numeric string", () => {
+    expect(() => parsePort("abc")).toThrow('Invalid port "abc"');
+  });
+
+  it("throws on empty string", () => {
+    expect(() => parsePort("")).toThrow('Invalid port ""');
+  });
+
+  it("truncates floating point to integer", () => {
+    expect(parsePort("80.5")).toBe(80);
+  });
+});
+
+describe("parseLogLevel", () => {
+  it.each(["none", "error", "warning", "info", "debug", "all"] as const)(
+    "accepts %s",
+    (level) => {
+      expect(parseLogLevel(level)).toBe(level);
+    },
+  );
+
+  it("throws on invalid level", () => {
+    expect(() => parseLogLevel("verbose")).toThrow('Invalid log level "verbose"');
+  });
+
+  it("throws on empty string", () => {
+    expect(() => parseLogLevel("")).toThrow('Invalid log level ""');
+  });
+});
+
+describe("parseHost", () => {
+  it("accepts 127.0.0.1", async () => {
+    await expect(parseHost("127.0.0.1")).resolves.toBe("127.0.0.1");
+  });
+
+  it("accepts 0.0.0.0", async () => {
+    await expect(parseHost("0.0.0.0")).resolves.toBe("0.0.0.0");
+  });
+
+  it("accepts localhost", async () => {
+    await expect(parseHost("localhost")).resolves.toBe("localhost");
+  });
+
+  it("accepts an IPv6 address", async () => {
+    await expect(parseHost("::1")).resolves.toBe("::1");
+  });
+
+  it("rejects an empty string", async () => {
+    await expect(parseHost("")).rejects.toThrow('Invalid host ""');
+  });
+
+  it("rejects an unresolvable hostname", async () => {
+    await expect(parseHost("not.a.real.host.invalid")).rejects.toThrow("Invalid host");
+  });
+
+  it("rejects a string with spaces", async () => {
+    await expect(parseHost("local host")).rejects.toThrow('Invalid host "local host"');
+  });
+});
+
+describe("parseLatency", () => {
+  it("parses a valid latency", () => {
+    expect(parseLatency("100")).toBe(100);
+  });
+
+  it("accepts zero", () => {
+    expect(parseLatency("0")).toBe(0);
+  });
+
+  it("throws on negative value", () => {
+    expect(() => parseLatency("-1")).toThrow('Invalid latency "-1"');
+  });
+
+  it("throws on non-numeric value", () => {
+    expect(() => parseLatency("abc")).toThrow('Invalid latency "abc"');
+  });
+
+  it("throws on empty string", () => {
+    expect(() => parseLatency("")).toThrow('Invalid latency ""');
+  });
+
+  it("truncates floating point to integer", () => {
+    expect(parseLatency("50.7")).toBe(50);
+  });
+});
+
+describe("parseChunkSize", () => {
+  it("parses a valid chunk size", () => {
+    expect(parseChunkSize("20")).toBe(20);
+  });
+
+  it("accepts zero", () => {
+    expect(parseChunkSize("0")).toBe(0);
+  });
+
+  it("throws on negative value", () => {
+    expect(() => parseChunkSize("-5")).toThrow('Invalid chunk size "-5"');
+  });
+
+  it("throws on non-numeric value", () => {
+    expect(() => parseChunkSize("abc")).toThrow('Invalid chunk size "abc"');
+  });
+});