feat: add requestTransform for deterministic matching and recording

iskhakovt · claude · iskhakovt · commit bac282ebd25e · 2026-03-30T17:49:10.000+01:00
Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/__tests__/router.test.ts b/src/__tests__/router.test.ts
@@ -601,3 +601,98 @@ describe("matchFixture — first-match-wins", () => {
     expect(matchFixture([noMatch, match], req)).toBe(match);
   });
 });
+
+// ---------------------------------------------------------------------------
+// matchFixture — requestTransform
+// ---------------------------------------------------------------------------
+
+describe("matchFixture — requestTransform", () => {
+  const stripTimestamp = (req: ChatCompletionRequest): ChatCompletionRequest => ({
+    ...req,
+    messages: req.messages.map((m) => ({
+      ...m,
+      content:
+        typeof m.content === "string"
+          ? m.content.replace(/\d{4}-\d{2}-\d{2}T[\d:.Z+-]+/g, "")
+          : m.content,
+    })),
+  });
+
+  it("uses exact equality for string userMessage when transform is set", () => {
+    const fixture = makeFixture({ userMessage: "Event:  happened" });
+    const req = makeReq({
+      messages: [{ role: "user", content: "Event: 2026-03-30T13:19:38Z happened" }],
+    });
+    // Without transform: substring "Event:  happened" is NOT in the original text
+    expect(matchFixture([fixture], req)).toBeNull();
+    // With transform: timestamps stripped, exact match succeeds
+    expect(matchFixture([fixture], req, undefined, stripTimestamp)).toBe(fixture);
+  });
+
+  it("substring match still works without transform", () => {
+    const fixture = makeFixture({ userMessage: "hello" });
+    const req = makeReq({ messages: [{ role: "user", content: "say hello world" }] });
+    expect(matchFixture([fixture], req)).toBe(fixture);
+  });
+
+  it("exact match rejects substring matches when transform is set", () => {
+    const identity = (req: ChatCompletionRequest): ChatCompletionRequest => req;
+    const fixture = makeFixture({ userMessage: "hello" });
+    const req = makeReq({ messages: [{ role: "user", content: "say hello world" }] });
+    // With transform (identity): exact match fails because "say hello world" !== "hello"
+    expect(matchFixture([fixture], req, undefined, identity)).toBeNull();
+  });
+
+  it("uses exact equality for string inputText when transform is set", () => {
+    const stripPrefix = (req: ChatCompletionRequest): ChatCompletionRequest => ({
+      ...req,
+      embeddingInput: req.embeddingInput?.split(" | ")[0],
+    });
+    const fixture = makeFixture({ inputText: "concept" });
+    const req = {
+      ...makeReq(),
+      embeddingInput: "concept | session-abc-123",
+    } as ChatCompletionRequest;
+    // Without transform: substring "concept" is in "concept | session-abc-123"
+    expect(matchFixture([fixture], req)).toBe(fixture);
+    // With transform: embeddingInput becomes "concept", exact match succeeds
+    expect(matchFixture([fixture], req, undefined, stripPrefix)).toBe(fixture);
+  });
+
+  it("exact inputText rejects substring matches when transform is set", () => {
+    const identity = (req: ChatCompletionRequest): ChatCompletionRequest => req;
+    const fixture = makeFixture({ inputText: "concept" });
+    const req = {
+      ...makeReq(),
+      embeddingInput: "concept | session-abc-123",
+    } as ChatCompletionRequest;
+    // With transform (identity): exact match fails
+    expect(matchFixture([fixture], req, undefined, identity)).toBeNull();
+  });
+
+  it("regexp matching still works with transform", () => {
+    // After stripTimestamp, content becomes "Event:  happened" (double space)
+    const fixture = makeFixture({ userMessage: /^Event:\s+happened$/ });
+    const req = makeReq({
+      messages: [{ role: "user", content: "Event: 2026-03-30T13:19:38Z happened" }],
+    });
+    // Regexp matches the transformed text
+    expect(matchFixture([fixture], req, undefined, stripTimestamp)).toBe(fixture);
+  });
+
+  it("predicate receives transformed request", () => {
+    let capturedModel = "";
+    const transform = (req: ChatCompletionRequest): ChatCompletionRequest => ({
+      ...req,
+      model: "transformed-model",
+    });
+    const fixture = makeFixture({
+      predicate: (r) => {
+        capturedModel = r.model;
+        return true;
+      },
+    });
+    matchFixture([fixture], makeReq({ model: "original-model" }), undefined, transform);
+    expect(capturedModel).toBe("transformed-model");
+  });
+});
diff --git a/src/bedrock-converse.ts b/src/bedrock-converse.ts
@@ -263,7 +263,12 @@ export async function handleConverse(
 
   const completionReq = converseToCompletionRequest(converseReq, modelId);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
@@ -466,7 +471,12 @@ export async function handleConverseStream(
 
   const completionReq = converseToCompletionRequest(converseReq, modelId);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/bedrock.ts b/src/bedrock.ts
@@ -309,7 +309,12 @@ export async function handleBedrock(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = bedrockToCompletionRequest(bedrockReq, modelId);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
@@ -626,7 +631,12 @@ export async function handleBedrockStream(
 
   const completionReq = bedrockToCompletionRequest(bedrockReq, modelId);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/cohere.ts b/src/cohere.ts
@@ -465,7 +465,12 @@ export async function handleCohere(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = cohereToCompletionRequest(cohereReq);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/embeddings.ts b/src/embeddings.ts
@@ -86,7 +86,12 @@ export async function handleEmbeddings(
     embeddingInput: combinedInput,
   };
 
-  const fixture = matchFixture(fixtures, syntheticReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    syntheticReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/gemini.ts b/src/gemini.ts
@@ -415,7 +415,12 @@ export async function handleGemini(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = geminiToCompletionRequest(geminiReq, model, streaming);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
   const path = req.url ?? `/v1beta/models/${model}:generateContent`;
 
   if (fixture) {
diff --git a/src/messages.ts b/src/messages.ts
@@ -464,7 +464,12 @@ export async function handleMessages(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = claudeToCompletionRequest(claudeReq);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/ollama.ts b/src/ollama.ts
@@ -342,7 +342,12 @@ export async function handleOllama(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = ollamaToCompletionRequest(ollamaReq);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
@@ -585,7 +590,12 @@ export async function handleOllamaGenerate(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = ollamaGenerateToCompletionRequest(generateReq);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/recorder.ts b/src/recorder.ts
@@ -31,7 +31,11 @@ export async function proxyAndRecord(
   providerKey: RecordProviderKey,
   pathname: string,
   fixtures: Fixture[],
-  defaults: { record?: RecordConfig; logger: Logger },
+  defaults: {
+    record?: RecordConfig;
+    logger: Logger;
+    requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest;
+  },
   rawBody?: string,
 ): Promise<boolean> {
   const record = defaults.record;
@@ -146,8 +150,9 @@ export async function proxyAndRecord(
     fixtureResponse = buildFixtureResponse(parsedResponse, upstreamStatus);
   }
 
-  // Build the match criteria from the original request
-  const fixtureMatch = buildFixtureMatch(request);
+  // Build the match criteria from the (optionally transformed) request
+  const effectiveRequest = defaults.requestTransform ? defaults.requestTransform(request) : request;
+  const fixtureMatch = buildFixtureMatch(effectiveRequest);
 
   // Build and save the fixture
   const fixture: Fixture = { match: fixtureMatch, response: fixtureResponse };
diff --git a/src/responses.ts b/src/responses.ts
@@ -527,7 +527,12 @@ export async function handleResponses(
   // Convert to ChatCompletionRequest for fixture matching
   const completionReq = responsesToCompletionRequest(responsesReq);
 
-  const fixture = matchFixture(fixtures, completionReq, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    completionReq,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
diff --git a/src/router.ts b/src/router.ts
@@ -27,63 +27,72 @@ export function matchFixture(
   fixtures: Fixture[],
   req: ChatCompletionRequest,
   matchCounts?: Map<Fixture, number>,
+  requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest,
 ): Fixture | null {
+  const effectiveReq = requestTransform ? requestTransform(req) : req;
+
   for (const fixture of fixtures) {
     const { match } = fixture;
 
     // predicate — if present, must return true
     if (match.predicate !== undefined) {
-      if (!match.predicate(req)) continue;
+      if (!match.predicate(effectiveReq)) continue;
     }
 
     // userMessage — match against the last user message content
     if (match.userMessage !== undefined) {
-      const msg = getLastMessageByRole(req.messages, "user");
+      const msg = getLastMessageByRole(effectiveReq.messages, "user");
       const text = msg ? getTextContent(msg.content) : null;
       if (!text) continue;
       if (typeof match.userMessage === "string") {
-        if (!text.includes(match.userMessage)) continue;
+        if (requestTransform ? text !== match.userMessage : !text.includes(match.userMessage))
+          continue;
       } else {
         if (!match.userMessage.test(text)) continue;
       }
     }
 
     // toolCallId — match against the last tool message's tool_call_id
     if (match.toolCallId !== undefined) {
-      const msg = getLastMessageByRole(req.messages, "tool");
+      const msg = getLastMessageByRole(effectiveReq.messages, "tool");
       if (!msg || msg.tool_call_id !== match.toolCallId) continue;
     }
 
     // toolName — match against any tool definition by function.name
     if (match.toolName !== undefined) {
-      const tools = req.tools ?? [];
+      const tools = effectiveReq.tools ?? [];
       const found = tools.some((t) => t.function.name === match.toolName);
       if (!found) continue;
     }
 
     // inputText — match against the embedding input text (used by embeddings endpoint)
     if (match.inputText !== undefined) {
-      const embeddingInput = req.embeddingInput;
+      const embeddingInput = effectiveReq.embeddingInput;
       if (!embeddingInput) continue;
       if (typeof match.inputText === "string") {
-        if (!embeddingInput.includes(match.inputText)) continue;
+        if (
+          requestTransform
+            ? embeddingInput !== match.inputText
+            : !embeddingInput.includes(match.inputText)
+        )
+          continue;
       } else {
         if (!match.inputText.test(embeddingInput)) continue;
       }
     }
 
     // responseFormat — exact string match against request response_format.type
     if (match.responseFormat !== undefined) {
-      const reqType = req.response_format?.type;
+      const reqType = effectiveReq.response_format?.type;
       if (reqType !== match.responseFormat) continue;
     }
 
     // model — exact string or regexp
     if (match.model !== undefined) {
       if (typeof match.model === "string") {
-        if (req.model !== match.model) continue;
+        if (effectiveReq.model !== match.model) continue;
       } else {
-        if (!match.model.test(req.model)) continue;
+        if (!match.model.test(effectiveReq.model)) continue;
       }
     }
 
diff --git a/src/server.ts b/src/server.ts
@@ -177,7 +177,12 @@ async function handleCompletions(
   }
 
   // Match fixture
-  const fixture = matchFixture(fixtures, body, journal.fixtureMatchCounts);
+  const fixture = matchFixture(
+    fixtures,
+    body,
+    journal.fixtureMatchCounts,
+    defaults.requestTransform,
+  );
 
   if (fixture) {
     journal.incrementFixtureMatchCount(fixture, fixtures);
@@ -391,6 +396,9 @@ export async function createServer(
     get strict() {
       return serverOptions.strict;
     },
+    get requestTransform() {
+      return serverOptions.requestTransform;
+    },
   };
 
   // Validate chaos config rates
diff --git a/src/types.ts b/src/types.ts
diff --git a/src/ws-gemini-live.ts b/src/ws-gemini-live.ts
diff --git a/src/ws-realtime.ts b/src/ws-realtime.ts
diff --git a/src/ws-responses.ts b/src/ws-responses.ts
