Unable to stream large files through MultipartRelatedOutput without full buffering (RESTEasy 6.2.10.Final)

[iasai1]

I'm working on a system that retrieves a large file via one API and forwards it to another API as part of a multipart/related request. My goal is to stream the file directly from the incoming source to the outgoing API without fully buffering it in memory or disk.

I'm using a Jakarta EE 10 / MicroProfile 6 compatible setup, deployed on a WF33-backed server, with the following versions:

Dependency	Version
Jakarta EE Web API	10.0.0
Jakarta WS RS API	3.1.0
MicroProfile Rest Client	3.0
MicroProfile Fault Tolerance API	4.0
MicroProfile Config API	3.1
MicroProfile JWT Auth API	2.1
Jackson	2.15.4
RESTEasy Multipart Provider	6.2.10.Final

What I'm doing:

1️⃣ I use a MicroProfile Rest Client to fetch an InputStream from the first API.
2️⃣ I wrap that stream in a MultipartRelatedOutput along with a small JSON part.
3️⃣ I send it using another MicroProfile Rest Client with the following method:

@POST
@Consumes("multipart/related; type=application/json")
@Produces(MediaType.APPLICATION_JSON)
UUID createDocument(MultipartRelatedOutput multipartOutput);

InputStream fileStream = firstApi.streamFile(fileId);
Document doc = buildDocument();
Map<String, InputStream> attachments = Map.of(doc.getAttachmentId(), fileStream);
MultipartRelatedOutput multipart = new MultipartRelatedOutput();
multipart.addPart(doc, MediaType.APPLICATION_JSON_TYPE);
attachments.forEach((attachmentId, stream) -> {
    multipart.addPart(stream, MediaType.APPLICATION_OCTET_STREAM_TYPE, attachmentId, "binary");
});
return secondApi.createDocument(multipart.toMultipart());

My expectation:

Since the part I’m passing to MultipartRelatedOutput is an InputStream, and debugging shows that the incoming stream works as expected (the stream is lazily obtained), I expect RESTEasy’s multipart writer to stream the data directly to the outgoing request.

What actually happens:

When the request is prepared, the process quickly returns the InputStream (no delays in fetching).
However, when the request is sent to the second API, the process hangs and starts consuming memory. After hitting the default 50 MB threshold, I receive:

RESTEASY005081: File limit of 50MB has been reached. The entity cannot be processed. Increase the size with the configuration property dev.resteasy.entity.file.threshold.

Debugging shows, that the problem does not occur while receiving the InputStream; it's fast and behaves as expected. The issue happens during sending, inside the multipart serialization and writing phase. The stack trace confirms that RESTEasy’s multipart writer calls the InputStreamProvider.writeTo(), which streams, but ultimately buffering seems to be enforced lower down by EntityOutputStream.checkFileThreshold().

RESTEASY004655: Unable to invoke request: java.lang.IllegalStateException: RESTEASY005081: File limit of 50MB has been reached. The entity cannot be processed. Increase the size with the configuration property dev.resteasy.entity.file.threshold.: jakarta.ws.rs.ProcessingException: RESTEASY004655: Unable to invoke request: java.lang.IllegalStateException: RESTEASY005081: File limit of 50MB has been reached. The entity cannot be processed. Increase the size with the configuration property dev.resteasy.entity.file.threshold.
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.engines.ManualClosingApacheHttpClient43Engine.invoke(ManualClosingApacheHttpClient43Engine.java:365)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.internal.ClientInvocation.invoke(ClientInvocation.java:427)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invokeSync(ClientInvoker.java:134)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invoke(ClientInvoker.java:103)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.internal.proxy.ClientProxy.invoke(ClientProxy.java:102)
...
Caused by: java.lang.IllegalStateException: RESTEASY005081: File limit of 50MB has been reached. The entity cannot be processed. Increase the size with the configuration property dev.resteasy.entity.file.threshold.
	at org.jboss.resteasy.resteasy-core-spi@6.2.10.Final//org.jboss.resteasy.spi.EntityOutputStream.checkFileThreshold(EntityOutputStream.java:324)
	at org.jboss.resteasy.resteasy-core-spi@6.2.10.Final//org.jboss.resteasy.spi.EntityOutputStream.getDelegate(EntityOutputStream.java:286)
	at org.jboss.resteasy.resteasy-core-spi@6.2.10.Final//org.jboss.resteasy.spi.EntityOutputStream.write(EntityOutputStream.java:180)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.util.DelegatingOutputStream.write(DelegatingOutputStream.java:40)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.util.DelegatingOutputStream.write(DelegatingOutputStream.java:40)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.HeaderFlushedOutputStream.write(HeaderFlushedOutputStream.java:68)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.plugins.providers.ProviderHelper.writeTo(ProviderHelper.java:122)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.plugins.providers.InputStreamProvider.writeTo(InputStreamProvider.java:54)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.plugins.providers.InputStreamProvider.writeTo(InputStreamProvider.java:27)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.AbstractMultipartWriter.writePart(AbstractMultipartWriter.java:113)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.AbstractMultipartWriter.writeParts(AbstractMultipartWriter.java:77)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.AbstractMultipartWriter.write(AbstractMultipartWriter.java:58)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.AbstractMultipartRelatedWriter.writeRelated(AbstractMultipartRelatedWriter.java:46)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.MultipartRelatedWriter.writeTo(MultipartRelatedWriter.java:47)
	at org.jboss.resteasy.resteasy-multipart-provider@6.2.10.Final//org.jboss.resteasy.plugins.providers.multipart.MultipartRelatedWriter.writeTo(MultipartRelatedWriter.java:26)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.core.interception.jaxrs.AbstractWriterInterceptorContext.writeTo(AbstractWriterInterceptorContext.java:261)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.core.interception.jaxrs.AbstractWriterInterceptorContext.syncProceed(AbstractWriterInterceptorContext.java:224)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.core.interception.jaxrs.AbstractWriterInterceptorContext.proceed(AbstractWriterInterceptorContext.java:207)
	at org.jboss.resteasy.resteasy-crypto@6.2.10.Final//org.jboss.resteasy.security.doseta.DigitalSigningInterceptor.aroundWriteTo(DigitalSigningInterceptor.java:108)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.core.interception.jaxrs.AbstractWriterInterceptorContext.syncProceed(AbstractWriterInterceptorContext.java:231)
	at org.jboss.resteasy.resteasy-core@6.2.10.Final//org.jboss.resteasy.core.interception.jaxrs.AbstractWriterInterceptorContext.proceed(AbstractWriterInterceptorContext.java:207)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.internal.ClientInvocation.writeRequestBody(ClientInvocation.java:387)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.engines.ManualClosingApacheHttpClient43Engine.writeRequestBodyToOutputStream(ManualClosingApacheHttpClient43Engine.java:579)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.engines.ManualClosingApacheHttpClient43Engine.buildEntity(ManualClosingApacheHttpClient43Engine.java:548)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.engines.ManualClosingApacheHttpClient43Engine.loadHttpMethod(ManualClosingApacheHttpClient43Engine.java:486)
	at org.jboss.resteasy.resteasy-client@6.2.10.Final//org.jboss.resteasy.client.jaxrs.engines.ManualClosingApacheHttpClient43Engine.invoke(ManualClosingApacheHttpClient43Engine.java:345)

My question:

Is there a supported way to disable full buffering of the multipart entity when using MultipartRelatedOutput + InputStream parts, so that true end-to-end streaming can happen? Or is the only viable approach to manually build the multipart body using StreamingOutput (or a custom writer)? I understand that buffering might be needed when Content-Length is unknown, but since my incoming file has a known length (from metadata of the first API), I am wondering if this could be leveraged to achieve streaming without full buffering.

[jamezp]

I'll have to try to create a reproducer unless you've already got one. Part of the reason for the limit is to avoid a DDoS or similar attacks.

[iasai1]

@jamezp I will give you a reproducer project soon

[iasai1]

https://github.com/iasai1/resteas-multipart-test

[jamezp]

Thank you. I'm not able to run the reproducer, but I see what the point is. I ran out of time today to look at this, but I'll make sure to have a loot early next early before I go on PTO.

[JSamir]

Hi James,

we are using microprofile-rest-client and pass a MultipartRelatedOutput object to one of the methods. The object contains two parts - one for the json and one for a file with size>50mb.

I assumed that there will be no buffering on resteasy side since using multipart/related is about efficiency (compared e.g. to encoding the file as base64 string inside the body). Therefore I was surprised to see that apparently buffering occurs in any case, regardless if mp-restclient or resteasy-client is being used. Setting chunked=true with resteasy-client does not help either, as this is probably only used when sending the request after it has been buffered.

So before investing more time here, can you tell if it's possible at all to prevent resteasy from buffering before sending out the request? All the attempts failed because ultimately EntityOutputStream is used and prevents streaming. We need to know if there is a way around that.

BR,
Samir

[jamezp]

I don't think there is currently a way around this, but it's definitely something I will look into.

[liweinan]

Here's a proposed solution provided by Grok that maybe useful:

Potential Solutions
Given that RESTEasy currently enforces buffering, here are possible approaches to address or work around the issue:

1. Increase the File Threshold (Temporary Workaround):

   • Increase the dev.resteasy.entity.file.threshold configuration property to allow larger files to be buffered, avoiding the 50 MB limit error.
   • Steps:
     • Add the following to your application configuration (e.g., microprofile-config.properties or WildFly’s configuration):

       dev.resteasy.entity.file.threshold=500

       (Set to 500 MB or higher, depending on your needs.)
     • Alternatively, set it programmatically if supported by your deployment:

       System.setProperty("dev.resteasy.entity.file.threshold", "500");

   • Pros: Quick fix to allow processing larger files without code changes.
   • Cons: Still buffers the entire file, which defeats the goal of streaming and may cause memory/disk issues for very large files. Not a long-term solution.

2. Use StreamingOutput for Manual Multipart Construction:

   • Bypass MultipartRelatedOutput and manually construct the multipart/related body using StreamingOutput to achieve true streaming.
   • Example:

     import jakarta.ws.rs.core.MediaType;
     import jakarta.ws.rs.core.Response;
     import jakarta.ws.rs.core.StreamingOutput;
     import java.io.InputStream;
     import java.io.OutputStream;
     import java.nio.charset.StandardCharsets;
     import java.util.UUID;
     
     @POST
     @Consumes("multipart/related; type=application/json")
     @Produces(MediaType.APPLICATION_JSON)
     public UUID createDocument(Document doc, InputStream fileStream) {
         StreamingOutput streamingOutput = output -> {
             writeMultipartRelated(output, doc, fileStream);
         };
         Response response = Response.ok(streamingOutput, "multipart/related; type=application/json").build();
         return secondApi.createDocument(response);
     }
     
     private void writeMultipartRelated(OutputStream output, Document doc, InputStream fileStream) throws Exception {
         String boundary = "boundary_" + UUID.randomUUID().toString();
         output.write(("--" + boundary + "\r\n").getBytes(StandardCharsets.UTF_8));
         
         // Write JSON part
         output.write(("Content-Type: application/json\r\n\r\n").getBytes(StandardCharsets.UTF_8));
         objectMapper.writeValue(output, doc);
         output.write(("\r\n--" + boundary + "\r\n").getBytes(StandardCharsets.UTF_8));
         
         // Write file part
         output.write(("Content-Type: application/octet-stream\r\n" +
                       "Content-ID: " + doc.getAttachmentId() + "\r\n" +
                       "Content-Transfer-Encoding: binary\r\n\r\n").getBytes(StandardCharsets.UTF_8));
         byte[] buffer = new byte[8192];
         int bytesRead;
         while ((bytesRead = fileStream.read(buffer)) != -1) {
             output.write(buffer, 0, bytesRead);
         }
         output.write(("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));
         output.flush();
     }

   • Steps:
     • Replace MultipartRelatedOutput with a StreamingOutput that manually writes the multipart/related structure.
     • Ensure proper boundary handling and headers for each part.
     • Use the known file length (from metadata) to set Content-Length if required, or rely on chunked transfer encoding.
   • Pros: Achieves true streaming, avoiding full buffering. Leverages the InputStream directly.
   • Cons: Requires manual construction of the multipart body, which is error-prone and less maintainable. May need additional error handling for stream interruptions.

3. Custom MessageBodyWriter:

   • Implement a custom MessageBodyWriter for MultipartRelatedOutput to handle streaming without buffering.
   • Example:

     import jakarta.ws.rs.core.MediaType;
     import jakarta.ws.rs.core.MultivaluedMap;
     import jakarta.ws.rs.ext.MessageBodyWriter;
     import jakarta.ws.rs.ext.Provider;
     import org.jboss.resteasy.plugins.providers.multipart.MultipartRelatedOutput;
     import java.io.InputStream;
     import java.io.OutputStream;
     import java.lang.annotation.Annotation;
     import java.lang.reflect.Type;
     
     @Provider
     @Produces("multipart/related")
     public class StreamingMultipartRelatedWriter implements MessageBodyWriter<MultipartRelatedOutput> {
         @Override
         public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
             return MultipartRelatedOutput.class.isAssignableFrom(type);
         }
     
         @Override
         public void writeTo(MultipartRelatedOutput multipart, Class<?> type, Type genericType, Annotation[] annotations,
                             MediaType mediaType, MultivaluedMap<String, Object> httpHeaders, OutputStream entityStream)
                 throws java.io.IOException {
             String boundary = "boundary_" + UUID.randomUUID().toString();
             httpHeaders.putSingle("Content-Type", "multipart/related; boundary=" + boundary);
     
             for (Object part : multipart.getParts()) {
                 entityStream.write(("--" + boundary + "\r\n").getBytes(StandardCharsets.UTF_8));
                 if (part instanceof InputStream) {
                     entityStream.write(("Content-Type: application/octet-stream\r\n\r\n").getBytes(StandardCharsets.UTF_8));
                     InputStream stream = (InputStream) part;
                     byte.ConcurrentHashMap<String, Object> buffer = new byte[8192];
                     int bytesRead;
                     while ((bytesRead = stream.read(buffer)) != -1) {
                         entityStream.write(buffer, 0, bytesRead);
                     }
                 } else {
                     entityStream.write(("Content-Type: application/json\r\n\r\n").getBytes(StandardCharsets.UTF_8));
                     objectMapper.writeValue(entityStream, part);
                 }
                 entityStream.write(("\r\n").getBytes(StandardCharsets.UTF_8));
             }
             entityStream.write(("--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));
             entityStream.flush();
         }
     }

   • Steps:
     • Register the custom MessageBodyWriter with @Provider in your application.
     • Ensure it takes precedence over RESTEasy’s default MultipartRelatedWriter.
   • Pros: Reusable and integrates with RESTEasy’s provider model. Avoids buffering for InputStream parts.
   • Cons: Complex to implement correctly, especially for all MultipartRelatedOutput scenarios. Requires thorough testing.

[JSamir]

1. is not really an option if one wants streaming.

The other options I already tried on Friday (or variations of those options, not sure anymore) and they did not work because at the end EntityOutputStream was still used, but I did not dig into details as to why it happened.