feat: Add PathPattern for extras wildcard matching

Author: thced

src/main/java/com/retailsvc/http/internal/PathPattern.java

@@ -0,0 +1,73 @@
+package com.retailsvc.http.internal;
+
+import java.util.regex.Pattern;
+
+public final class PathPattern {
+
+  private final String raw;
+  private final Pattern regex;
+  private final boolean wildcard;
+
+  private PathPattern(String raw, Pattern regex, boolean wildcard) {
+    this.raw = raw;
+    this.regex = regex;
+    this.wildcard = wildcard;
+  }
+
+  public static PathPattern compile(String raw) {
+    if (raw == null || !raw.startsWith("/")) {
+      throw new IllegalArgumentException("path must start with '/': " + raw);
+    }
+    String[] segments = raw.substring(1).split("/", -1);
+    StringBuilder rx = new StringBuilder("^");
+    boolean hasWildcard = false;
+    String prev = null;
+    for (int i = 0; i < segments.length; i++) {
+      String seg = segments[i];
+      if (seg.isEmpty()
+          && !(i == segments.length - 1 && segments.length > 1 && raw.endsWith("/"))) {
+        throw new IllegalArgumentException("empty segment in path: " + raw);
+      }
+      if (seg.contains("*") && !seg.equals("*") && !seg.equals("**")) {
+        throw new IllegalArgumentException(
+            "'*' and '**' must be a whole segment, not " + seg + " in " + raw);
+      }
+      if ("**".equals(seg) && "**".equals(prev)) {
+        throw new IllegalArgumentException("adjacent '**' segments in " + raw);
+      }
+      boolean trailing = i == segments.length - 1;
+      switch (seg) {
+        case "*" -> {
+          rx.append("/[^/]+");
+          hasWildcard = true;
+        }
+        case "**" -> {
+          if (trailing) {
+            // Slash is required; anything (including empty string) may follow it.
+            rx.append("/.*");
+          } else {
+            // At least one character and a slash must appear before the next segment.
+            rx.append("/.+");
+          }
+          hasWildcard = true;
+        }
+        default -> rx.append("/").append(Pattern.quote(seg));
+      }
+      prev = seg;
+    }
+    rx.append("$");
+    return new PathPattern(raw, Pattern.compile(rx.toString()), hasWildcard);
+  }
+
+  public boolean hasWildcard() {
+    return wildcard;
+  }
+
+  public boolean matches(String path) {
+    return regex.matcher(path).matches();
+  }
+
+  public String raw() {
+    return raw;
+  }
+}

src/test/java/com/retailsvc/http/internal/PathPatternTest.java

@@ -0,0 +1,75 @@
+package com.retailsvc.http.internal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.junit.jupiter.api.Test;
+
+class PathPatternTest {
+
+  @Test
+  void exactPathHasNoWildcardAndMatchesItself() {
+    PathPattern p = PathPattern.compile("/alive");
+    assertThat(p.hasWildcard()).isFalse();
+    assertThat(p.matches("/alive")).isTrue();
+    assertThat(p.matches("/alive/")).isFalse();
+    assertThat(p.matches("/alive232")).isFalse();
+  }
+
+  @Test
+  void singleStarMatchesOneSegment() {
+    PathPattern p = PathPattern.compile("/files/*");
+    assertThat(p.hasWildcard()).isTrue();
+    assertThat(p.matches("/files/a")).isTrue();
+    assertThat(p.matches("/files/abc.txt")).isTrue();
+    assertThat(p.matches("/files/")).isFalse();
+    assertThat(p.matches("/files/a/b")).isFalse();
+  }
+
+  @Test
+  void doubleStarMatchesAnyDepth() {
+    PathPattern p = PathPattern.compile("/files/**");
+    assertThat(p.matches("/files/")).isTrue();
+    assertThat(p.matches("/files/a")).isTrue();
+    assertThat(p.matches("/files/a/b/c")).isTrue();
+    assertThat(p.matches("/files")).isFalse();
+    assertThat(p.matches("/filesx/a")).isFalse();
+  }
+
+  @Test
+  void midPathDoubleStarSurroundedByLiterals() {
+    PathPattern p = PathPattern.compile("/schemas/**/openapi.yaml");
+    assertThat(p.matches("/schemas/a/openapi.yaml")).isTrue();
+    assertThat(p.matches("/schemas/a/b/openapi.yaml")).isTrue();
+    assertThat(p.matches("/schemas/openapi.yaml")).isFalse();
+    assertThat(p.matches("/schemas/a/openapi.yamlx")).isFalse();
+  }
+
+  @Test
+  void mixedSegmentRejected() {
+    assertThatThrownBy(() -> PathPattern.compile("/files/prefix-*.json"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("must be a whole segment");
+  }
+
+  @Test
+  void emptySegmentRejected() {
+    assertThatThrownBy(() -> PathPattern.compile("/files//a"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("empty segment");
+  }
+
+  @Test
+  void adjacentDoubleStarsRejected() {
+    assertThatThrownBy(() -> PathPattern.compile("/a/**/**/b"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("adjacent");
+  }
+
+  @Test
+  void mustStartWithSlash() {
+    assertThatThrownBy(() -> PathPattern.compile("files/*"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("must start with '/'");
+  }
+}