feat: Add InputStream-based Spec loaders for classpath specs

thced · thced · commit b1b6c665c8cc · 2026-05-20T10:45:37.000+02:00
Spec.fromPath required a filesystem Path, which is awkward for callers
loading the spec from the classpath via getResourceAsStream and outright
broken when the resource lives inside a JAR.

Add four new entry points:

- Spec.fromJson(InputStream)                       — Gson (reflective)
- Spec.fromJson(InputStream, Function&lt;byte[],Map&gt;) — BYO parser (Jackson, ...)
- Spec.fromYaml(InputStream)                       — SnakeYAML (reflective)
- Spec.fromYaml(InputStream, Function&lt;byte[],Map&gt;) — BYO parser

All four consume and close the stream, NPE on null args, and surface IO
failures as UncheckedIOException. fromPath now shares the same byte-based
internal parsers.

Also ignore .claude/worktrees/ so local agent worktrees don't pollute
git status.
diff --git a/.gitignore b/.gitignore
@@ -36,6 +36,7 @@ build/
 
 ### Claude Code per-developer settings ###
 .claude/settings.local.json
+.claude/worktrees/
 
 ### Performance recordings ###
 perf/
diff --git a/src/main/java/com/retailsvc/http/spec/Spec.java b/src/main/java/com/retailsvc/http/spec/Spec.java
@@ -6,17 +6,21 @@
 import com.retailsvc.http.spec.security.SecurityScheme;
 import com.retailsvc.http.spec.security.SecuritySchemeParser;
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.UncheckedIOException;
 import java.lang.reflect.Method;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
+import java.util.function.Function;
 
 public record Spec(
     String openapi,
@@ -67,18 +71,18 @@ static Map<String, Object> extractExtensions(Map<String, Object> raw) {
    *     has an unrecognised extension
    */
   public static Spec fromPath(Path path) {
-    String text;
+    byte[] bytes;
     try {
-      text = Files.readString(path);
+      bytes = Files.readAllBytes(path);
     } catch (IOException e) {
       throw new UncheckedIOException("Failed to read OpenAPI spec from " + path, e);
     }
     String name = path.getFileName().toString().toLowerCase(Locale.ROOT);
     Map<String, Object> raw;
     if (name.endsWith(".json")) {
-      raw = parseJson(text);
+      raw = parseJsonWithGson(bytes);
     } else if (name.endsWith(".yaml") || name.endsWith(".yml")) {
-      raw = parseYaml(text);
+      raw = parseYamlWithSnakeYaml(bytes);
     } else {
       throw new IllegalStateException(
           "Unrecognised OpenAPI spec extension for "
@@ -89,8 +93,89 @@ public static Spec fromPath(Path path) {
     return from(raw);
   }
 
-  private static Map<String, Object> parseJson(String text) {
-    Class<?> gsonClass = loadOptional(GSON_CLASS, "JSON", "Gson");
+  /**
+   * Reads a JSON OpenAPI specification from {@code in} using Gson. Gson must be on the classpath;
+   * otherwise throws {@link IllegalStateException}. The stream is fully consumed and closed before
+   * this method returns.
+   *
+   * <p>Useful for loading specs from the classpath:
+   *
+   * <pre>{@code
+   * try (InputStream in = getClass().getResourceAsStream("/openapi.json")) {
+   *   Spec spec = Spec.fromJson(in);
+   * }
+   * }</pre>
+   *
+   * <p>To avoid the Gson dependency (e.g. when using Jackson), use {@link #fromJson(InputStream,
+   * Function)} instead.
+   *
+   * @throws NullPointerException if {@code in} is {@code null}
+   * @throws UncheckedIOException if the stream cannot be read
+   * @throws IllegalStateException if Gson is not on the classpath
+   */
+  public static Spec fromJson(InputStream in) {
+    return fromJson(in, Spec::parseJsonWithGson);
+  }
+
+  /**
+   * Reads a JSON OpenAPI specification from {@code in} using the supplied {@code parser}. The
+   * parser receives the full body as bytes and returns the decoded map. The stream is fully
+   * consumed and closed before this method returns.
+   *
+   * <p>Example with Jackson:
+   *
+   * <pre>{@code
+   * ObjectMapper mapper = new ObjectMapper();
+   * Spec spec = Spec.fromJson(in, bytes -> mapper.readValue(bytes, Map.class));
+   * }</pre>
+   *
+   * @throws NullPointerException if {@code in} or {@code parser} is {@code null}
+   * @throws UncheckedIOException if the stream cannot be read
+   */
+  public static Spec fromJson(InputStream in, Function<byte[], Map<String, Object>> parser) {
+    Objects.requireNonNull(parser, "parser");
+    return from(parser.apply(readAll(in)));
+  }
+
+  /**
+   * Reads a YAML OpenAPI specification from {@code in} using SnakeYAML. SnakeYAML must be on the
+   * classpath; otherwise throws {@link IllegalStateException}. The stream is fully consumed and
+   * closed before this method returns.
+   *
+   * <p>To avoid the SnakeYAML dependency, use {@link #fromYaml(InputStream, Function)} instead.
+   *
+   * @throws NullPointerException if {@code in} is {@code null}
+   * @throws UncheckedIOException if the stream cannot be read
+   * @throws IllegalStateException if SnakeYAML is not on the classpath
+   */
+  public static Spec fromYaml(InputStream in) {
+    return fromYaml(in, Spec::parseYamlWithSnakeYaml);
+  }
+
+  /**
+   * Reads a YAML OpenAPI specification from {@code in} using the supplied {@code parser}. The
+   * stream is fully consumed and closed before this method returns.
+   *
+   * @throws NullPointerException if {@code in} or {@code parser} is {@code null}
+   * @throws UncheckedIOException if the stream cannot be read
+   */
+  public static Spec fromYaml(InputStream in, Function<byte[], Map<String, Object>> parser) {
+    Objects.requireNonNull(parser, "parser");
+    return from(parser.apply(readAll(in)));
+  }
+
+  private static byte[] readAll(InputStream in) {
+    Objects.requireNonNull(in, "in");
+    try (in) {
+      return in.readAllBytes();
+    } catch (IOException e) {
+      throw new UncheckedIOException("Failed to read OpenAPI spec from stream", e);
+    }
+  }
+
+  private static Map<String, Object> parseJsonWithGson(byte[] bytes) {
+    String text = new String(bytes, StandardCharsets.UTF_8);
+    Class<?> gsonClass = loadOptional(GSON_CLASS, "Json", "Gson");
     try {
       Object gson = gsonClass.getDeclaredConstructor().newInstance();
       Method fromJson = gsonClass.getMethod("fromJson", String.class, Class.class);
@@ -102,8 +187,9 @@ private static Map<String, Object> parseJson(String text) {
     }
   }
 
-  private static Map<String, Object> parseYaml(String text) {
-    Class<?> yamlClass = loadOptional(SNAKEYAML_CLASS, "YAML", "SnakeYAML");
+  private static Map<String, Object> parseYamlWithSnakeYaml(byte[] bytes) {
+    String text = new String(bytes, StandardCharsets.UTF_8);
+    Class<?> yamlClass = loadOptional(SNAKEYAML_CLASS, "Yaml", "SnakeYAML");
     try {
       Object yaml = yamlClass.getDeclaredConstructor().newInstance();
       Method load = yamlClass.getMethod("load", String.class);
@@ -120,14 +206,15 @@ private static Class<?> loadOptional(String className, String format, String lib
       return Class.forName(className, false, Spec.class.getClassLoader());
     } catch (ClassNotFoundException e) {
       throw new IllegalStateException(
-          "Spec.fromPath requires "
-              + libName
-              + " on the classpath for "
+          "Loading "
               + format
-              + " specs. Add a "
+              + " OpenAPI specs requires "
               + libName
-              + " dependency, or parse the file yourself and call"
-              + " Spec.from(Map<String, Object>) instead.",
+              + " on the classpath. Add a "
+              + libName
+              + " dependency, or supply your own parser via Spec.from"
+              + format
+              + "(InputStream, Function) / Spec.from(Map<String, Object>) instead.",
           e);
     }
   }
diff --git a/src/test/java/com/retailsvc/http/spec/SpecFromInputStreamTest.java b/src/test/java/com/retailsvc/http/spec/SpecFromInputStreamTest.java
@@ -0,0 +1,185 @@
+package com.retailsvc.http.spec;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.google.gson.Gson;
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.Function;
+import org.junit.jupiter.api.Test;
+import org.yaml.snakeyaml.Yaml;
+
+class SpecFromInputStreamTest {
+
+  @Test
+  void fromJsonLoadsClasspathStreamUsingGson() throws Exception {
+    try (InputStream in = getClass().getResourceAsStream("/openapi.json")) {
+      Spec spec = Spec.fromJson(in);
+
+      assertThat(spec.openapi()).startsWith("3.1");
+      assertThat(spec.basePath()).isEqualTo("/api/v1");
+      assertThat(spec.operations()).isNotEmpty();
+    }
+  }
+
+  @Test
+  void fromYamlLoadsClasspathStreamUsingSnakeYaml() throws Exception {
+    try (InputStream in = getClass().getResourceAsStream("/openapi.yaml")) {
+      Spec spec = Spec.fromYaml(in);
+
+      assertThat(spec.openapi()).startsWith("3.1");
+      assertThat(spec.operations()).isNotEmpty();
+    }
+  }
+
+  @Test
+  void fromJsonWithCustomParserDoesNotRequireGson() throws Exception {
+    Gson gson = new Gson();
+    Function<byte[], Map<String, Object>> parser =
+        bytes -> gson.fromJson(new String(bytes, StandardCharsets.UTF_8), Map.class);
+
+    try (InputStream in = getClass().getResourceAsStream("/openapi.json")) {
+      Spec spec = Spec.fromJson(in, parser);
+
+      assertThat(spec.openapi()).startsWith("3.1");
+    }
+  }
+
+  @Test
+  void fromYamlWithCustomParserDoesNotRequireSnakeYaml() throws Exception {
+    Yaml yaml = new Yaml();
+    Function<byte[], Map<String, Object>> parser =
+        bytes -> yaml.load(new String(bytes, StandardCharsets.UTF_8));
+
+    try (InputStream in = getClass().getResourceAsStream("/openapi.yaml")) {
+      Spec spec = Spec.fromYaml(in, parser);
+
+      assertThat(spec.openapi()).startsWith("3.1");
+    }
+  }
+
+  @Test
+  void fromJsonClosesStream() throws Exception {
+    AtomicBoolean closed = new AtomicBoolean(false);
+    try (InputStream raw = getClass().getResourceAsStream("/openapi.json")) {
+      InputStream tracking = closingTracker(raw, closed);
+
+      Spec.fromJson(tracking);
+
+      assertThat(closed).isTrue();
+    }
+  }
+
+  @Test
+  void fromYamlClosesStream() throws Exception {
+    AtomicBoolean closed = new AtomicBoolean(false);
+    try (InputStream raw = getClass().getResourceAsStream("/openapi.yaml")) {
+      InputStream tracking = closingTracker(raw, closed);
+
+      Spec.fromYaml(tracking);
+
+      assertThat(closed).isTrue();
+    }
+  }
+
+  @Test
+  void fromJsonWithParserClosesStream() {
+    AtomicBoolean closed = new AtomicBoolean(false);
+    String json =
+        "{\"openapi\":\"3.1.0\",\"info\":{\"title\":\"t\",\"version\":\"1\"},"
+            + "\"servers\":[{\"url\":\"http://localhost/x\"}],\"paths\":{}}";
+    InputStream tracking =
+        closingTracker(new ByteArrayInputStream(json.getBytes(StandardCharsets.UTF_8)), closed);
+    Gson gson = new Gson();
+    Function<byte[], Map<String, Object>> parser =
+        bytes -> gson.fromJson(new String(bytes, StandardCharsets.UTF_8), Map.class);
+
+    Spec.fromJson(tracking, parser);
+
+    assertThat(closed).isTrue();
+  }
+
+  @Test
+  void fromJsonRejectsNullStream() {
+    assertThatThrownBy(() -> Spec.fromJson((InputStream) null))
+        .isInstanceOf(NullPointerException.class);
+  }
+
+  @Test
+  void fromYamlRejectsNullStream() {
+    assertThatThrownBy(() -> Spec.fromYaml((InputStream) null))
+        .isInstanceOf(NullPointerException.class);
+  }
+
+  @Test
+  void fromJsonWithParserRejectsNullArgs() {
+    InputStream in = new ByteArrayInputStream(new byte[0]);
+    Function<byte[], Map<String, Object>> parser = bytes -> Map.of();
+
+    assertThatThrownBy(() -> Spec.fromJson(null, parser)).isInstanceOf(NullPointerException.class);
+    assertThatThrownBy(() -> Spec.fromJson(in, null)).isInstanceOf(NullPointerException.class);
+  }
+
+  @Test
+  void fromYamlWithParserRejectsNullArgs() {
+    InputStream in = new ByteArrayInputStream(new byte[0]);
+    Function<byte[], Map<String, Object>> parser = bytes -> Map.of();
+
+    assertThatThrownBy(() -> Spec.fromYaml(null, parser)).isInstanceOf(NullPointerException.class);
+    assertThatThrownBy(() -> Spec.fromYaml(in, null)).isInstanceOf(NullPointerException.class);
+  }
+
+  @Test
+  void fromJsonPropagatesIoFailure() {
+    InputStream broken = brokenStream();
+
+    assertThatThrownBy(() -> Spec.fromJson(broken)).isInstanceOf(UncheckedIOException.class);
+  }
+
+  @Test
+  void fromYamlPropagatesIoFailure() {
+    InputStream broken = brokenStream();
+
+    assertThatThrownBy(() -> Spec.fromYaml(broken)).isInstanceOf(UncheckedIOException.class);
+  }
+
+  private static InputStream closingTracker(InputStream delegate, AtomicBoolean flag) {
+    return new InputStream() {
+      @Override
+      public int read() throws IOException {
+        return delegate.read();
+      }
+
+      @Override
+      public int read(byte[] b, int off, int len) throws IOException {
+        return delegate.read(b, off, len);
+      }
+
+      @Override
+      public void close() throws IOException {
+        flag.set(true);
+        delegate.close();
+      }
+    };
+  }
+
+  private static InputStream brokenStream() {
+    return new InputStream() {
+      @Override
+      public int read() throws IOException {
+        throw new IOException("boom");
+      }
+
+      @Override
+      public int read(byte[] b, int off, int len) throws IOException {
+        throw new IOException("boom");
+      }
+    };
+  }
+}
