llm-mock-server 1.0.1 → 1.0.3

package/src/mock-server.ts

@@ -1,9 +1,17 @@
 import Fastify from "fastify";
 import type { FastifyInstance } from "fastify";
 import type {
-  Match, PendingRule, Reply, ReplyOptions, Resolver, Rule, RuleHandle, RuleSummary, SequenceEntry,
+  Match,
+  PendingRule,
+  Reply,
+  ReplyOptions,
+  Resolver,
+  Rule,
+  RuleHandle,
+  RuleSummary,
+  SequenceEntry,
 } from "./types.js";
-import { RuleEngine } from "./rule-engine.js";
+import { RuleEngine, createSequenceResolver } from "./rule-engine.js";
 import { RequestHistory } from "./history.js";
 import { openaiFormat } from "./formats/openai/index.js";
 import { anthropicFormat } from "./formats/anthropic/index.js";
@@ -13,7 +21,11 @@ import { Logger } from "./logger.js";
 import type { LogLevel } from "./logger.js";
 import { createRouteHandler } from "./route-handler.js";
 
-const formats: readonly Format[] = [openaiFormat, anthropicFormat, responsesFormat];
+const formats: readonly Format[] = [
+  openaiFormat,
+  anthropicFormat,
+  responsesFormat,
+];
 
 export interface MockServerOptions {
   readonly port?: number;
@@ -56,8 +68,12 @@ export class MockServer {
     this.host = options.host ?? "127.0.0.1";
     this.logger = new Logger(options.logLevel ?? "none");
     this.defaultOptions = {
-      ...(options.defaultLatency !== undefined && { latency: options.defaultLatency }),
-      ...(options.defaultChunkSize !== undefined && { chunkSize: options.defaultChunkSize }),
+      ...(options.defaultLatency !== undefined && {
+        latency: options.defaultLatency,
+      }),
+      ...(options.defaultChunkSize !== undefined && {
+        chunkSize: options.defaultChunkSize,
+      }),
     };
     this.app = Fastify({ logger: false });
 
@@ -103,19 +119,15 @@ export class MockServer {
         return makeHandle(engine.add(match, response, options));
       },
       replySequence(entries: readonly SequenceEntry[]): RuleHandle {
-        if (entries.length === 0) throw new Error("replySequence requires at least one entry.");
-        let index = 0;
-        const last = entries[entries.length - 1]!;
-        const rule = engine.add(match, () => {
-          const entry = entries[index++] ?? last;
-          if (typeof entry === "string" || !("reply" in entry)) {
-            rule.options = {};
-            return entry;
-          }
-          rule.options = entry.options ?? {};
-          return entry.reply;
-        });
-        rule.remaining = entries.length;
+        const steps = entries.map((entry) =>
+          typeof entry === "string" || !("reply" in entry)
+            ? { reply: entry as Reply }
+            : { reply: entry.reply, options: entry.options },
+        );
+        const rule = engine.add(match, "");
+        const { resolver, entryCount } = createSequenceResolver(steps, rule);
+        rule.resolve = resolver;
+        rule.remaining = entryCount;
         return makeHandle(rule);
       },
     };
@@ -175,10 +187,14 @@ export class MockServer {
     const { loadRulesFromPath } = await import("./loader.js");
     await loadRulesFromPath(pathOrDir, {
       engine: this.engine,
-      setFallback: (reply) => { this.fallbackReply = reply; },
+      setFallback: (reply) => {
+        this.fallbackReply = reply;
+      },
     });
     const loaded = this.engine.ruleCount - before;
-    this.logger.info(`Loaded ${loaded} rule${loaded !== 1 ? "s" : ""} from ${pathOrDir}`);
+    this.logger.info(
+      `Loaded ${loaded} rule${loaded !== 1 ? "s" : ""} from ${pathOrDir}`,
+    );
   }
 
   /** Every request the server has handled. */
@@ -201,7 +217,8 @@ export class MockServer {
 
   /** The base URL the server is listening on, e.g. `http://127.0.0.1:12345`. Throws if the server hasn't started. */
   get url(): string {
-    if (!this.listening) throw new Error("Server is not running. Call start() first.");
+    if (!this.listening)
+      throw new Error("Server is not running. Call start() first.");
     const addr = this.app.server.address();
     const port = addr !== null && typeof addr === "object" ? addr.port : 0;
     return `http://${this.host}:${port}`;

package/src/route-handler.ts

@@ -1,6 +1,12 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { ZodError } from "zod";
-import type { Reply, ReplyObject, ReplyOptions, MockRequest, Rule } from "./types.js";
+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";
@@ -21,14 +27,17 @@ async function resolveReply(
   logger: Logger,
 ): Promise<{ reply: ReplyObject; ruleDesc: string | undefined }> {
   if (!matched) {
-    logger.warn(`No matching rule for "${mockReq.lastMessage}", using fallback`);
+    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;
+    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) {
@@ -37,7 +46,7 @@ async function resolveReply(
   }
 }
 
-export interface RouteHandlerDeps {
+interface RouteHandlerDeps {
   engine: RuleEngine;
   history: RequestHistory;
   logger: Logger;
@@ -45,7 +54,10 @@ export interface RouteHandlerDeps {
   getFallback: () => Reply;
 }
 
-export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
+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) => {
@@ -61,10 +73,19 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
       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" }),
+        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;
     }
@@ -76,14 +97,20 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
 
     const matched = engine.match(mockReq);
     const { reply: resolvedReply, ruleDesc } = await resolveReply(
-      matched, mockReq, getFallback(), logger,
+      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));
+      return reply
+        .status(error.status)
+        .type("application/json")
+        .send(format.serializeError(error));
     }
 
     history.record(mockReq, ruleDesc);
@@ -100,14 +127,22 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
       logger.debug(`Reply text: "${resolvedReply.text}"`);
     }
     if (resolvedReply.tools?.length) {
-      logger.debug(`Reply tool calls: ${resolvedReply.tools.map((t) => t.name).join(", ")}`);
+      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));
+      return reply
+        .type("application/json")
+        .send(format.serializeComplete(resolvedReply, mockReq.model));
     }
 
-    const chunks = format.serialize(resolvedReply, mockReq.model, effectiveOptions);
+    const chunks = format.serialize(
+      resolvedReply,
+      mockReq.model,
+      effectiveOptions,
+    );
     await writeSSE(reply, chunks, effectiveOptions);
   };
 }

package/src/rule-engine.ts

@@ -1,7 +1,18 @@
-import type { Match, MatchObject, MockRequest, Resolver, ReplyOptions, Rule, RuleSummary } from "./types.js";
+import type {
+  Match,
+  MatchObject,
+  MockRequest,
+  Resolver,
+  Reply,
+  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;
+  return re.global || re.sticky
+    ? new RegExp(re.source, re.flags.replace(/[gy]/g, ""))
+    : re;
 }
 
 function compilePattern(pattern: string | RegExp): (value: string) => boolean {
@@ -26,16 +37,21 @@ function compileMatcher(match: Match): (req: MockRequest) => boolean {
     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;
+  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.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;
   };
@@ -52,7 +68,12 @@ function describeMatch(match: Match): string {
   return `{${parts.join(", ")}}`;
 }
 
-function createRule(match: Match, resolve: Resolver, options: ReplyOptions, description?: string): Rule {
+function createRule(
+  match: Match,
+  resolve: Resolver,
+  options: ReplyOptions,
+  description?: string,
+): Rule {
   return {
     description: description ?? describeMatch(match),
     match: compileMatcher(match),
@@ -62,6 +83,29 @@ function createRule(match: Match, resolve: Resolver, options: ReplyOptions, desc
   };
 }
 
+interface SequenceStep {
+  readonly reply: Reply;
+  readonly options?: ReplyOptions | undefined;
+}
+
+export function createSequenceResolver(
+  steps: readonly SequenceStep[],
+  rule: { options: ReplyOptions },
+): { resolver: () => Reply; entryCount: number } {
+  if (steps.length === 0)
+    throw new Error("Sequence requires at least one entry.");
+  let index = 0;
+  const last = steps[steps.length - 1]!;
+  return {
+    resolver: () => {
+      const step = steps[index++] ?? last;
+      rule.options = step.options ?? {};
+      return step.reply;
+    },
+    entryCount: steps.length,
+  };
+}
+
 export class RuleEngine {
   private readonly rules: Rule[] = [];
 
@@ -79,7 +123,11 @@ export class RuleEngine {
     }
   }
 
-  addHandler(matchFn: (req: MockRequest) => boolean, respond: Resolver, description = "(handler)"): Rule {
+  addHandler(
+    matchFn: (req: MockRequest) => boolean,
+    respond: Resolver,
+    description = "(handler)",
+  ): Rule {
     const rule = createRule(matchFn, respond, {}, description);
     this.rules.push(rule);
     return rule;
@@ -102,7 +150,9 @@ export class RuleEngine {
   }
 
   isDone(): boolean {
-    return this.rules.every((r) => !Number.isFinite(r.remaining) || r.remaining <= 0);
+    return this.rules.every(
+      (r) => !Number.isFinite(r.remaining) || r.remaining <= 0,
+    );
   }
 
   get ruleCount(): number {
@@ -110,7 +160,10 @@ export class RuleEngine {
   }
 
   describe(): readonly RuleSummary[] {
-    return this.rules.map((r) => ({ description: r.description, remaining: r.remaining }));
+    return this.rules.map((r) => ({
+      description: r.description,
+      remaining: r.remaining,
+    }));
   }
 
   clear(): void {

package/src/types/reply.ts

@@ -5,30 +5,28 @@ 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;
+  /** 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. */
+  /** 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. */
+  /** Auto-generated if omitted. */
   readonly id?: string | undefined;
   readonly name: string;
   readonly args: Readonly<Record<string, unknown>>;
@@ -37,13 +35,15 @@ export interface ToolCall {
 /** 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. */
+/** Per-rule streaming options. Merged with server-level defaults, with per-rule values winning. */
 export interface ReplyOptions {
-  /** Milliseconds to wait between SSE chunks. */
+  /** Milliseconds between SSE chunks. */
   readonly latency?: number | undefined;
-  /** Split text into chunks of this many characters for more realistic streaming. */
+  /** Characters per SSE chunk 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 };
+export type SequenceEntry =
+  | Reply
+  | { readonly reply: Reply; readonly options?: ReplyOptions };

package/src/types/request.ts

@@ -3,28 +3,24 @@ 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. */
+  /** Empty string 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. */
+  /** Pulled out from `tools` for quick lookups. */
   readonly toolNames: readonly string[];
-  /** If the last message was a tool result, this is its `tool_call_id`. */
+  /** Set when the last message was a tool result. */
   readonly lastToolCallId: string | undefined;
-  /** The raw request body, in case you need something we don't extract. */
+  /** The raw request body, for anything 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`. */
+  /** e.g. `/v1/chat/completions` */
   readonly path: string;
 }
 
@@ -32,7 +28,7 @@ export interface MockRequest {
 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. */
+  /** Links the result back to its tool call. Only set on `"tool"` messages. */
   readonly toolCallId?: string | undefined;
 }
 
@@ -40,6 +36,6 @@ export interface Message {
 export interface ToolDef {
   readonly name: string;
   readonly description?: string | undefined;
-  /** JSON Schema for the tool's parameters, passed through as-is. */
+  /** JSON Schema, passed through as-is. */
   readonly parameters?: unknown;
 }

package/src/types/rule.ts

@@ -17,13 +17,9 @@ export type Match =
 
 /** 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;
@@ -36,15 +32,13 @@ export interface MatchObject {
 /** 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. */
+  /** Each match advances through the array. The last entry repeats once 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;
 }
 
@@ -59,16 +53,15 @@ export interface Handler {
 
 /** 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. */
+  /** `Infinity` means unlimited. */
   readonly remaining: number;
 }
 
 export interface Rule {
   readonly description: string;
   readonly match: (req: MockRequest) => boolean;
-  readonly resolve: Resolver;
+  resolve: Resolver;
   options: ReplyOptions;
   remaining: number;
 }

package/src/types.ts

@@ -1,5 +1,24 @@
 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";
+  FormatName,
+  MockRequest,
+  Message,
+  ToolDef,
+} from "./types/request.js";
+export type {
+  Reply,
+  ReplyObject,
+  ErrorReply,
+  ToolCall,
+  Resolver,
+  ReplyOptions,
+  SequenceEntry,
+} from "./types/reply.js";
+export type {
+  Match,
+  MatchObject,
+  PendingRule,
+  RuleHandle,
+  RuleSummary,
+  Handler,
+  Rule,
+} from "./types/rule.js";

package/test/cli-validators.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { parsePort, parseHost, parseChunkSize, parseLogLevel, parseLatency } from "../src/cli-validators.js";
+import {
+  parsePort,
+  parseHost,
+  parseChunkSize,
+  parseLogLevel,
+  parseLatency,
+} from "../src/cli-validators.js";
 
 describe("parsePort", () => {
   it("parses a valid port", () => {
@@ -48,7 +54,9 @@ describe("parseLogLevel", () => {
   );
 
   it("throws on invalid level", () => {
-    expect(() => parseLogLevel("verbose")).toThrow('Invalid log level "verbose"');
+    expect(() => parseLogLevel("verbose")).toThrow(
+      'Invalid log level "verbose"',
+    );
   });
 
   it("throws on empty string", () => {
@@ -78,11 +86,15 @@ describe("parseHost", () => {
   });
 
   it("rejects an unresolvable hostname", async () => {
-    await expect(parseHost("not.a.real.host.invalid")).rejects.toThrow("Invalid host");
+    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"');
+    await expect(parseHost("local host")).rejects.toThrow(
+      'Invalid host "local host"',
+    );
   });
 });