feat(spec): Add PathTemplate value object with regex extraction

Author: thced

src/main/java/com/retailsvc/http/spec/PathTemplate.java

@@ -0,0 +1,40 @@
+package com.retailsvc.http.spec;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public record PathTemplate(String raw, Pattern compiled, List<String> parameterNames) {
+
+  private static final Pattern TOKEN = Pattern.compile("\\{([^/}]+)}");
+
+  public static PathTemplate compile(String template) {
+    StringBuilder regex = new StringBuilder("^");
+    List<String> names = new ArrayList<>();
+    Matcher m = TOKEN.matcher(template);
+    int last = 0;
+    while (m.find()) {
+      regex.append(Pattern.quote(template.substring(last, m.start())));
+      regex.append("([^/]+)");
+      names.add(m.group(1));
+      last = m.end();
+    }
+    regex.append(Pattern.quote(template.substring(last)));
+    regex.append("$");
+    return new PathTemplate(template, Pattern.compile(regex.toString()), List.copyOf(names));
+  }
+
+  public Optional<Map<String, String>> match(String path) {
+    Matcher m = compiled.matcher(path);
+    if (!m.matches()) return Optional.empty();
+    Map<String, String> out = new LinkedHashMap<>();
+    for (int i = 0; i < parameterNames.size(); i++) {
+      out.put(parameterNames.get(i), m.group(i + 1));
+    }
+    return Optional.of(Map.copyOf(out));
+  }
+}

src/test/java/com/retailsvc/http/spec/PathTemplateTest.java

@@ -0,0 +1,44 @@
+package com.retailsvc.http.spec;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+class PathTemplateTest {
+  @Test
+  void exactPathMatchesItself() {
+    PathTemplate t = PathTemplate.compile("/users");
+    assertThat(t.match("/users")).isPresent();
+    assertThat(t.match("/users").get()).isEmpty();
+  }
+
+  @Test
+  void exactPathDoesNotMatchOther() {
+    assertThat(PathTemplate.compile("/users").match("/orders")).isEmpty();
+  }
+
+  @Test
+  void singleParamExtracted() {
+    PathTemplate t = PathTemplate.compile("/users/{id}");
+    assertThat(t.match("/users/42"))
+        .hasValueSatisfying(m -> assertThat(m).containsEntry("id", "42"));
+    assertThat(t.parameterNames()).containsExactly("id");
+  }
+
+  @Test
+  void twoParamsExtracted() {
+    PathTemplate t = PathTemplate.compile("/orgs/{org}/repos/{repo}");
+    var m = t.match("/orgs/acme/repos/widget").orElseThrow();
+    assertThat(m).containsEntry("org", "acme").containsEntry("repo", "widget");
+  }
+
+  @Test
+  void doesNotMatchSlashesInsideParam() {
+    assertThat(PathTemplate.compile("/users/{id}").match("/users/42/foo")).isEmpty();
+  }
+
+  @Test
+  void rawIsPreserved() {
+    assertThat(PathTemplate.compile("/users/{id}").raw()).isEqualTo("/users/{id}");
+  }
+}