Merge pull request quarkusio#50343 from geoand/streaming-docs

Add example of sending back a file with `RestResponse

Author: geoand

.github/workflows/jdk-early-access-build.yml

@@ -21,7 +21,7 @@ env:
   # Workaround testsuite locale issue
   LANG: en_US.UTF-8
   MAVEN_OPTS: -Xmx2g -XX:MaxMetaspaceSize=1g
-  JVM_TEST_MAVEN_OPTS: "-e -B --settings .github/mvn-settings.xml -Dtest-containers -Dstart-containers -Dtest-resteasy-reactive-large-files -Dformat.skip"
+  JVM_TEST_MAVEN_OPTS: "-e -B --settings .github/mvn-settings.xml -Dtest-containers -Dstart-containers -Dtest-resteasy-reactive-large-files -Dquarkus.test.rest-assured.enable-logging-on-failure=false -Dformat.skip"
   DB_USER: hibernate_orm_test
   DB_PASSWORD: hibernate_orm_test
   DB_NAME: hibernate_orm_test
@@ -139,4 +139,4 @@ jobs:
           issue-repository: ${{ github.repository }}
           issue-number: 15867
           quarkus-sha: ${{ steps.quarkus-sha.outputs.sha }}
-          project-sha: ${{ steps.quarkus-sha.outputs.sha }}
+          project-sha: ${{ steps.quarkus-sha.outputs.sha }}

docs/src/main/asciidoc/rest.adoc

@@ -778,6 +778,34 @@ public class Endpoint {
 NOTE: You can also use the Jakarta REST type link:{jaxrsapi}/jakarta/ws/rs/core/Response.html[`Response`] but it is
 not strongly typed to your entity.
 
+==== Responding with files
+
+When a file needs to be returned, the following code ensures that Quarkus properly streams the file contents to the client.
+
+[source,java]
+----
+package org.acme.rest;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import org.jboss.resteasy.reactive.RestResponse;
+import org.jboss.resteasy.reactive.RestResponse.ResponseBuilder;
+
+@Path("")
+public class Endpoint {
+
+    @Path("file")
+    @GET
+    public RestResponse<java.nio.file.Path> largePathRestResponse() throws IOException {
+        java.nio.file.Path path = ...
+
+        return RestResponse.ResponseBuilder.ok(path)
+                .header(HttpHeaders.CONTENT_DISPOSITION, "some-file-name")
+                .build();
+    }
+}
+----
+
 ==== Using annotations
 
 Alternatively, if you only need to set the status code and / or HTTP headers with static values, you can use `@org.jboss.resteasy.reactive.ResponseStatus` and /or `ResponseHeader` respectively.

extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/providers/FileResource.java

@@ -1,10 +1,13 @@
 package io.quarkus.resteasy.reactive.server.test.providers;
 
 import java.io.File;
+import java.io.IOException;
+import java.io.RandomAccessFile;
 import java.nio.file.Paths;
 
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.HttpHeaders;
 
 import org.jboss.resteasy.reactive.FilePart;
 import org.jboss.resteasy.reactive.PathPart;
@@ -91,4 +94,19 @@ public Uni<AsyncFile> getAsyncFilePartial(RoutingContext vertxRequest) {
             });
         });
     }
+
+    static final long ONE_GIGA = 1024L * 1024L * 1024L;
+
+    @Path("large-path-rest-response")
+    @GET
+    public RestResponse<java.nio.file.Path> largePathRestResponse() throws IOException {
+        File largeFile = File.createTempFile("rr-large-file-rest-response", ".tmp");
+        largeFile.deleteOnExit();
+        RandomAccessFile f = new RandomAccessFile(largeFile, "rw");
+        f.setLength(ONE_GIGA);
+
+        return RestResponse.ResponseBuilder.ok(largeFile.toPath())
+                .header(HttpHeaders.CONTENT_DISPOSITION, "large-file")
+                .build();
+    }
 }

extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/providers/FileTestCase.java

@@ -14,6 +14,7 @@
 import org.jboss.resteasy.reactive.PathPart;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.quarkus.test.QuarkusUnitTest;
@@ -168,4 +169,16 @@ public void testChecks() throws IOException {
         } catch (IllegalArgumentException x) {
         }
     }
+
+    @EnabledIfSystemProperty(named = "test-resteasy-reactive-large-files", matches = "true")
+    @Test
+    public void testWithLargeFile() {
+        RestAssured.given()
+                .get("/providers/file/large-path-rest-response")
+                .then()
+                .statusCode(200)
+                .contentType("application/octet-stream")
+                .header(HttpHeaders.CONTENT_DISPOSITION, "large-file")
+                .header(HttpHeaders.CONTENT_LENGTH, "1073741824");
+    }
 }