chore: added ProxyResponse.materializeTo() utility method

Author: quintesse

src/main/java/org/codejive/tproxy/ProxyResponse.java

@@ -3,6 +3,10 @@
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
 import java.util.Objects;
 import java.util.function.Supplier;
 
@@ -18,14 +22,13 @@
  * <p>The {@link #body()} method materializes the stream into a byte array and caches it, so
  * subsequent calls return the same cached array.
  *
- * <p><b>Important for Interceptors:</b> If your interceptor needs to read the body, you must create
- * a new {@code ProxyResponse} with a re-readable body source. For example:
+ * <p><b>Important for Interceptors:</b> If your interceptor needs to read the body, you can use
+ * {@link #materializeTo(Path)} to save it to a file and get a re-readable response:
  *
  * <pre>{@code
  * ProxyResponse original = chain.proceed(request);
  * Path tempFile = Files.createTempFile("proxy", ".tmp");
- * Files.copy(original.bodyStream(), tempFile, StandardCopyOption.REPLACE_EXISTING);
- * return original.withBody(() -> Files.newInputStream(tempFile));
+ * return original.materializeTo(tempFile);
  * }</pre>
  */
 public class ProxyResponse {
@@ -256,6 +259,33 @@ public ProxyResponse withBody(Supplier<InputStream> bodySupplier) {
         return ProxyResponse.fromSupplier(statusCode, headers, bodySupplier);
     }
 
+    /**
+     * Materialize the response body to a file and return a new ProxyResponse with a re-readable
+     * body source that reads from the file. This is useful for interceptors that need to read the
+     * body multiple times.
+     *
+     * <p>The body stream is copied to the specified file, replacing it if it already exists. The
+     * returned ProxyResponse will have a supplier-based body that opens a new InputStream from the
+     * file on each call to {@link #bodyStream()}.
+     *
+     * @param path the file path to write the body to
+     * @return a new ProxyResponse with a supplier that reads from the file
+     * @throws IOException if an I/O error occurs while writing to the file
+     */
+    public ProxyResponse materializeTo(Path path) throws IOException {
+        try (InputStream bodyStream = bodyStream()) {
+            Files.copy(bodyStream, path, StandardCopyOption.REPLACE_EXISTING);
+        }
+        return withBody(
+                () -> {
+                    try {
+                        return Files.newInputStream(path);
+                    } catch (IOException e) {
+                        throw new UncheckedIOException("Failed to read from " + path, e);
+                    }
+                });
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

src/test/java/org/codejive/tproxy/StreamingProxyTest.java

@@ -7,9 +7,12 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.Random;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
 
 /** Tests for streaming body support in ProxyRequest and ProxyResponse. */
 @DisplayName("Streaming Proxy Tests")
@@ -167,6 +170,53 @@ public void testSupplierBasedBody() throws IOException {
         assertThat(content2).isEqualTo("repeatable data");
     }
 
+    @Test
+    @DisplayName("materializeTo() saves body to file and returns re-readable response")
+    public void testMaterializeTo(@TempDir Path tempDir) throws IOException {
+        // Create a response with a single-use stream
+        InputStream stream = new ByteArrayInputStream("test content for file".getBytes());
+        ProxyResponse response = ProxyResponse.fromStream(200, Headers.empty(), stream);
+
+        // Materialize to a temp file
+        Path tempFile = tempDir.resolve("response.bin");
+        ProxyResponse materialized = response.materializeTo(tempFile);
+
+        // Verify file was created and contains the body
+        assertThat(tempFile).exists();
+        String fileContent = Files.readString(tempFile);
+        assertThat(fileContent).isEqualTo("test content for file");
+
+        // Verify the materialized response is re-readable
+        String content1 = new String(materialized.bodyStream().readAllBytes());
+        assertThat(content1).isEqualTo("test content for file");
+
+        String content2 = new String(materialized.bodyStream().readAllBytes());
+        assertThat(content2).isEqualTo("test content for file");
+
+        // Verify status code and headers are preserved
+        assertThat(materialized.statusCode()).isEqualTo(200);
+        assertThat(materialized.headers()).isEqualTo(Headers.empty());
+    }
+
+    @Test
+    @DisplayName("materializeTo() replaces existing file")
+    public void testMaterializeToReplacesFile(@TempDir Path tempDir) throws IOException {
+        Path tempFile = tempDir.resolve("response.bin");
+
+        // Create a file with existing content
+        Files.writeString(tempFile, "old content");
+        assertThat(Files.readString(tempFile)).isEqualTo("old content");
+
+        // Materialize new content to the same file
+        ProxyResponse response =
+                ProxyResponse.fromBytes(200, Headers.empty(), "new content".getBytes());
+        ProxyResponse materialized = response.materializeTo(tempFile);
+
+        // Verify file was replaced
+        assertThat(Files.readString(tempFile)).isEqualTo("new content");
+        assertThat(new String(materialized.bodyStream().readAllBytes())).isEqualTo("new content");
+    }
+
     /**
      * Virtual InputStream that generates data on-the-fly without allocating large byte arrays. This
      * simulates a large response body for testing streaming without using excessive memory.