fix(mock): disambiguate template-path siblings by body bindings

When a recording captures the same verb+template (e.g. three calls to
GET /pet/{petId} with petId = 3, 5, 10) the matcher now scores each
hit by how many request-path bindings line up with the recorded request
body and returns the best match — so the mock answers /pet/5 with the
response captured for petId=5 instead of always returning the first
template hit. Literal-path matches still short-circuit and ties keep
the historical first-match-wins order, so single-step recordings and
legacy captures without body data are unchanged.

Author: thomas-stegemann

src/Kuestenlogik.Bowire.Mock/Matchers/ExactMatcher.cs

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Collections.Concurrent;
+using System.Text.Json;
 using System.Text.RegularExpressions;
 using Kuestenlogik.Bowire.Mocking;
 
@@ -24,7 +25,14 @@ namespace Kuestenlogik.Bowire.Mock.Matchers;
 /// <c>/{service}/{method}</c> URL path.
 /// </item>
 /// </list>
-/// Non-unary steps are always skipped; the first matching step wins.
+/// Non-unary steps are always skipped. When several recorded steps share
+/// the same verb + path template (e.g. three captures of
+/// <c>GET /pet/{petId}</c> with <c>petId</c> = 3, 5, 10), the matcher
+/// scores each candidate by how well its recorded request body matches the
+/// incoming path-bindings and picks the best hit — so a mock call against
+/// <c>/pet/5</c> returns the response for <c>petId = 5</c> instead of
+/// always handing back the first capture. Ties (and the historical
+/// single-template path) keep the original "first match wins" order.
 /// Phase 2 later adds a topic matcher for MQTT / Socket.IO wildcards as a
 /// separate <see cref="IMockMatcher"/> implementation.
 /// </summary>
@@ -35,13 +43,24 @@ public sealed class ExactMatcher : IMockMatcher
     // is shared across every incoming request.
     private static readonly ConcurrentDictionary<string, Regex> s_templateCache = new(StringComparer.Ordinal);
 
+    // Score handed back for a non-template match (literal path equality or
+    // a gRPC/Socket.IO candidate where the matcher has no further axis to
+    // rank on). Higher than any plausible body-binding count so a literal
+    // hit short-circuits before the matcher inspects the rest of the list,
+    // preserving the original "first literal match wins" contract.
+    private const int LiteralOrNonRestMatchScore = 1_000_000;
+
     public bool TryMatch(MockRequest request, BowireRecording recording, out BowireRecordingStep matchedStep)
     {
         ArgumentNullException.ThrowIfNull(request);
         ArgumentNullException.ThrowIfNull(recording);
 
+        BowireRecordingStep? bestStep = null;
+        var bestScore = -1;
+
         foreach (var candidate in recording.Steps)
         {
+            int score;
             // Skip protocol-shaped steps that don't match the request family.
             // Replay-ability (unary vs streaming, sent-messages for duplex) is
             // the replayer's concern — here we only pair incoming wire shape
@@ -50,6 +69,7 @@ public bool TryMatch(MockRequest request, BowireRecording recording, out BowireR
             {
                 if (!IsGrpcStep(candidate)) continue;
                 if (!MatchesGrpcPath(candidate, request)) continue;
+                score = LiteralOrNonRestMatchScore;
             }
             else if (IsSocketIoStep(candidate))
             {
@@ -59,21 +79,119 @@ public bool TryMatch(MockRequest request, BowireRecording recording, out BowireR
                 // instead: any GET upgrade on /socket.io/* pairs
                 // against the first socketio step in the recording.
                 if (!MatchesSocketIoRequest(request)) continue;
+                score = LiteralOrNonRestMatchScore;
             }
             else
             {
                 if (!IsRestStep(candidate)) continue;
                 if (!MatchesRestVerbAndPath(candidate, request)) continue;
+                score = ScoreRestCandidate(candidate, request);
+            }
+
+            if (score > bestScore)
+            {
+                bestStep = candidate;
+                bestScore = score;
             }
 
-            matchedStep = candidate;
+            // Literal / non-REST matches don't get any extra signal from
+            // body inspection, so the first one always wins — short-circuit
+            // to preserve the historical order-of-capture tie-break.
+            if (bestScore >= LiteralOrNonRestMatchScore) break;
+        }
+
+        if (bestStep is not null)
+        {
+            matchedStep = bestStep;
             return true;
         }
 
         matchedStep = null!;
         return false;
     }
 
+    /// <summary>
+    /// Rank a REST candidate that already passed verb + path-or-template
+    /// matching. Literal-path hits always outrank template hits (no body
+    /// inspection needed). For template hits, the score counts how many of
+    /// the captured path bindings (e.g. <c>petId = 5</c>) line up with the
+    /// recorded request body — a step recorded against <c>petId = 5</c>
+    /// outranks a sibling recorded against <c>petId = 3</c> when the
+    /// incoming request asks for pet 5. Missing / unparseable bodies score
+    /// zero and the historical "first match wins" tie-break takes over.
+    /// </summary>
+    private static int ScoreRestCandidate(BowireRecordingStep step, MockRequest request)
+    {
+        var template = step.HttpPath!;
+        if (!IsTemplate(template))
+        {
+            // Literal-path equality already filtered out non-matches in
+            // MatchesRestVerbAndPath; everyone here is an exact hit.
+            return LiteralOrNonRestMatchScore;
+        }
+
+        var bindings = ExtractTemplateBindings(template, request.Path);
+        if (bindings is null || bindings.Count == 0) return 0;
+        if (string.IsNullOrWhiteSpace(step.Body)) return 0;
+
+        Dictionary<string, string>? bodyValues;
+        try
+        {
+            bodyValues = ParseBodyStringValues(step.Body!);
+        }
+        catch (JsonException)
+        {
+            return 0;
+        }
+
+        if (bodyValues is null || bodyValues.Count == 0) return 0;
+
+        var matched = 0;
+        foreach (var (name, value) in bindings)
+        {
+            if (bodyValues.TryGetValue(name, out var recorded)
+                && string.Equals(recorded, value, StringComparison.Ordinal))
+            {
+                matched++;
+            }
+        }
+        return matched;
+    }
+
+    /// <summary>
+    /// Flatten a step body into a name → string-form map. The recorder
+    /// keeps the captured input as the JSON the user submitted (e.g.
+    /// <c>{"petId":3}</c>); we coerce primitive values to their canonical
+    /// text form so the matcher can compare them against URL-decoded path
+    /// segments without caring whether the user typed a number or a string.
+    /// </summary>
+    private static Dictionary<string, string>? ParseBodyStringValues(string bodyJson)
+    {
+        using var doc = JsonDocument.Parse(bodyJson);
+        if (doc.RootElement.ValueKind != JsonValueKind.Object) return null;
+
+        var map = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var prop in doc.RootElement.EnumerateObject())
+        {
+            var v = prop.Value;
+            switch (v.ValueKind)
+            {
+                case JsonValueKind.String:
+                    map[prop.Name] = v.GetString() ?? string.Empty;
+                    break;
+                case JsonValueKind.Number:
+                case JsonValueKind.True:
+                case JsonValueKind.False:
+                    map[prop.Name] = v.GetRawText();
+                    break;
+                default:
+                    // Arrays / objects don't appear in path bindings — skip.
+                    break;
+            }
+        }
+        return map;
+    }
+
     private static bool IsRestStep(BowireRecordingStep s) =>
         !string.IsNullOrEmpty(s.HttpPath) &&
         !string.IsNullOrEmpty(s.HttpVerb);

tests/Kuestenlogik.Bowire.Mock.Tests/ExactMatcherTests.cs

@@ -259,4 +259,105 @@ public void TryMatch_LiteralPath_StillMatchesExactly()
         Assert.False(matcher.TryMatch(Req("GET", "/WEATHER"), rec, out _));  // path case-sensitive
         Assert.False(matcher.TryMatch(Req("GET", "/weather/extra"), rec, out _));
     }
+
+    // ---- Body-bound disambiguation across siblings sharing a template ----
+
+    private static BowireRecordingStep RestStepWithBody(
+        string verb, string path, string body, string response) => new()
+    {
+        Id = "step_" + Guid.NewGuid().ToString("N")[..8],
+        Protocol = "rest",
+        Service = "PetService",
+        Method = "GetPetById",
+        MethodType = "Unary",
+        HttpPath = path,
+        HttpVerb = verb,
+        Body = body,
+        Status = "OK",
+        Response = response
+    };
+
+    [Fact]
+    public void TryMatch_OnTemplatePath_PrefersStepWhoseBodyBindingMatchesRequestPath()
+    {
+        // Three captures of GET /pet/{petId} with petId = 3, 5, 10. A mock
+        // call against /pet/5 must return the response captured for petId=5,
+        // not the first matching template hit.
+        var matcher = new ExactMatcher();
+        var rec = MakeRecording(
+            RestStepWithBody("GET", "/pet/{petId}", """{"petId":3}""", """{"id":3}"""),
+            RestStepWithBody("GET", "/pet/{petId}", """{"petId":5}""", """{"id":5}"""),
+            RestStepWithBody("GET", "/pet/{petId}", """{"petId":10}""", """{"id":10}"""));
+
+        Assert.True(matcher.TryMatch(Req("GET", "/pet/5"), rec, out var step));
+        Assert.Equal("""{"id":5}""", step.Response);
+    }
+
+    [Fact]
+    public void TryMatch_OnTemplatePath_BodyBindingHandlesStringValues()
+    {
+        // Path bindings arrive as URL segments (strings); the recorded body
+        // may carry the value as a string literal. Compare on the canonical
+        // text form so quoted-string captures still match.
+        var matcher = new ExactMatcher();
+        var rec = MakeRecording(
+            RestStepWithBody("GET", "/users/{id}", """{"id":"alice"}""", """{"name":"A"}"""),
+            RestStepWithBody("GET", "/users/{id}", """{"id":"bob"}""", """{"name":"B"}"""));
+
+        Assert.True(matcher.TryMatch(Req("GET", "/users/bob"), rec, out var step));
+        Assert.Equal("""{"name":"B"}""", step.Response);
+    }
+
+    [Fact]
+    public void TryMatch_OnTemplatePath_NoBodyBindingMatch_FallsBackToFirstHit()
+    {
+        // None of the recorded steps carry a body field that maps to the
+        // request's path binding. The matcher has no signal to pick between
+        // them — the historical "first match in capture order wins" tie-break
+        // takes over so legacy recordings keep working.
+        var matcher = new ExactMatcher();
+        var rec = MakeRecording(
+            RestStepWithBody("GET", "/pet/{petId}", "{}", """{"id":1}"""),
+            RestStepWithBody("GET", "/pet/{petId}", "{}", """{"id":2}"""));
+
+        Assert.True(matcher.TryMatch(Req("GET", "/pet/42"), rec, out var step));
+        Assert.Equal("""{"id":1}""", step.Response);
+    }
+
+    [Fact]
+    public void TryMatch_OnTemplatePath_MalformedBody_FallsBackToFirstHit()
+    {
+        // A recording whose body isn't parseable JSON (e.g. legacy free-text
+        // capture) shouldn't blow up the matcher — it just scores zero and
+        // the first template hit still wins.
+        var matcher = new ExactMatcher();
+        var rec = MakeRecording(
+            RestStepWithBody("GET", "/pet/{petId}", "not-json", """{"id":1}"""),
+            RestStepWithBody("GET", "/pet/{petId}", """{"petId":7}""", """{"id":7}"""));
+
+        // Request for pet 7 still finds the right body-bound step.
+        Assert.True(matcher.TryMatch(Req("GET", "/pet/7"), rec, out var step7));
+        Assert.Equal("""{"id":7}""", step7.Response);
+
+        // Request for an id that nobody recorded falls back to the first
+        // template hit (the malformed-body one).
+        Assert.True(matcher.TryMatch(Req("GET", "/pet/99"), rec, out var stepFallback));
+        Assert.Equal("""{"id":1}""", stepFallback.Response);
+    }
+
+    [Fact]
+    public void TryMatch_OnTemplatePath_MultipleBindings_PrefersBestBodyOverlap()
+    {
+        // Two-parameter template /users/{uid}/posts/{pid}: the step that
+        // matches BOTH bindings outranks the one that matches only one.
+        var matcher = new ExactMatcher();
+        var rec = MakeRecording(
+            RestStepWithBody("GET", "/users/{uid}/posts/{pid}",
+                """{"uid":42,"pid":1}""", """{"post":"first"}"""),
+            RestStepWithBody("GET", "/users/{uid}/posts/{pid}",
+                """{"uid":42,"pid":7}""", """{"post":"seventh"}"""));
+
+        Assert.True(matcher.TryMatch(Req("GET", "/users/42/posts/7"), rec, out var step));
+        Assert.Equal("""{"post":"seventh"}""", step.Response);
+    }
 }