Add streaming support to MVC functional endpoints

Prior to this commit, MVC function endpoints would allow Server Sent
Event responses through `ServerResponse.sse()`. While this covers a
common use case for streaming responses, other technologies would
benefit from a "low-level", unopinionated streaming support.

This commit introduces a new `BodyBuilder.stream()` methods that enables
such use cases. Developers are in charge of setting the relevant HTTP
response headers beforehand, and then can write to the response as raw
`String`, `byte[]` or using complex objects and the configured message
converters for serialization.

Because each streaming protocol has different message separator
semantics, it is also the developers' responsibility to flush buffered
content to the network once a message has been fully written.

Closes gh-32710

Author: bclozel

Diff for: spring-webmvc/src/main/java/org/springframework/web/servlet/function/DefaultServerResponseBuilder.java

@@ -209,6 +209,10 @@ public ServerResponse render(String name, Map<String, ?> model) {
 				.build();
 	}
 
+	@Override
+	public ServerResponse stream(Consumer<ServerResponse.StreamBuilder> streamConsumer) {
+		return StreamingServerResponse.create(this.statusCode, this.headers, this.cookies, streamConsumer, null);
+	}
 
 	private static class WriteFunctionResponse extends AbstractServerResponse {
 

Diff for: spring-webmvc/src/main/java/org/springframework/web/servlet/function/ServerResponse.java

@@ -547,6 +547,87 @@ interface BodyBuilder extends HeadersBuilder<BodyBuilder> {
 		 * @return the built response
 		 */
 		ServerResponse render(String name, Map<String, ?> model);
+
+		/**
+		 * Create a low-level streaming response; for SSE support, see {@link #sse(Consumer)}.
+		 * <p>The {@link StreamBuilder} provided to the {@code streamConsumer} can
+		 * be used to write to the response in a streaming fashion. Note, the builder is
+		 * responsible for flushing the buffered content to the network.
+		 * <p>For example:
+		 * <pre class="code">
+		 * public ServerResponse handleStream(ServerRequest request) {
+		 *     return ServerResponse.ok()
+		 *       .contentType(MediaType.APPLICATION_ND_JSON)
+		 *       .stream(stream -&gt; {
+		 *         try {
+		 *           // Write and flush a first item
+		 *           stream.write(new Person("John", 51), MediaType.APPLICATION_JSON)
+		 *             .write(new byte[]{'\n'})
+		 *             .flush();
+		 *           // Write and complete with the last item
+		 *           stream.write(new Person("Jane", 42), MediaType.APPLICATION_JSON)
+		 *             .write(new byte[]{'\n'})
+		 *             .complete();
+		 *         }
+		 *         catch (IOException ex) {
+		 *           throw new UncheckedIOException(ex);
+		 *         }
+		 *     });
+		 * }
+		 * </pre>
+		 * @param streamConsumer consumer that will be provided with a stream builder
+		 * @return the server-side streaming response
+		 * @since 6.2
+		 */
+		ServerResponse stream(Consumer<StreamBuilder> streamConsumer);
+
+	}
+
+	/**
+	 * Defines a builder for async response bodies.
+	 * @since 6.2
+	 * @param <B> the builder subclass
+	 */
+	interface AsyncBuilder<B extends AsyncBuilder<B>> {
+
+		/**
+		 * Completes the stream with the given error.
+		 *
+		 * <p>The throwable is dispatched back into Spring MVC, and passed to
+		 * its exception handling mechanism. Since the response has
+		 * been committed by this point, the response status can not change.
+		 * @param t the throwable to dispatch
+		 */
+		void error(Throwable t);
+
+		/**
+		 * Completes the stream.
+		 */
+		void complete();
+
+		/**
+		 * Register a callback to be invoked when a request times
+		 * out.
+		 * @param onTimeout the callback to invoke on timeout
+		 * @return this builder
+		 */
+		B onTimeout(Runnable onTimeout);
+
+		/**
+		 * Register a callback to be invoked when an error occurs during
+		 * processing.
+		 * @param onError the callback to invoke on error
+		 * @return this builder
+		 */
+		B onError(Consumer<Throwable> onError);
+
+		/**
+		 * Register a callback to be invoked when the request completes.
+		 * @param onCompletion the callback to invoked on completion
+		 * @return this builder
+		 */
+		B onComplete(Runnable onCompletion);
+
 	}
 
 
@@ -555,7 +636,7 @@ interface BodyBuilder extends HeadersBuilder<BodyBuilder> {
 	 *
 	 * @since 5.3.2
 	 */
-	interface SseBuilder {
+	interface SseBuilder extends AsyncBuilder<SseBuilder> {
 
 		/**
 		 * Sends the given object as a server-sent event.
@@ -618,45 +699,45 @@ interface SseBuilder {
 		 */
 		void data(Object object) throws IOException;
 
-		/**
-		 * Completes the event stream with the given error.
-		 *
-		 * <p>The throwable is dispatched back into Spring MVC, and passed to
-		 * its exception handling mechanism. Since the response has
-		 * been committed by this point, the response status can not change.
- 		 * @param t the throwable to dispatch
-		 */
-		void error(Throwable t);
+	}
 
-		/**
-		 * Completes the event stream.
-		 */
-		void complete();
+	/**
+	 * Defines a builder for a streaming response body.
+	 *
+	 * @since 6.2
+	 */
+	interface StreamBuilder extends AsyncBuilder<StreamBuilder> {
 
 		/**
-		 * Register a callback to be invoked when an SSE request times
-		 * out.
-		 * @param onTimeout the callback to invoke on timeout
+		 * Write the given object to the response stream, without flushing.
+		 * Strings will be sent as UTF-8 encoded bytes, byte arrays will be sent as-is,
+		 * and other objects will be converted into JSON using
+		 * {@linkplain HttpMessageConverter message converters}.
+		 * @param object the object to send as data
 		 * @return this builder
+		 * @throws IOException in case of I/O errors
 		 */
-		SseBuilder onTimeout(Runnable onTimeout);
+		StreamBuilder write(Object object) throws IOException;
 
 		/**
-		 * Register a callback to be invoked when an error occurs during SSE
-		 * processing.
-		 * @param onError the callback to invoke on error
+		 * Write the given object to the response stream, without flushing.
+		 * Strings will be sent as UTF-8 encoded bytes, byte arrays will be sent as-is,
+		 * and other objects will be converted into JSON using
+		 * {@linkplain HttpMessageConverter message converters}.
+		 * @param object the object to send as data
+		 * @param mediaType the media type to use for encoding the provided data
 		 * @return this builder
+		 * @throws IOException in case of I/O errors
 		 */
-		SseBuilder onError(Consumer<Throwable> onError);
+		StreamBuilder write(Object object, @Nullable MediaType mediaType) throws IOException;
 
 		/**
-		 * Register a callback to be invoked when the SSE request completes.
-		 * @param onCompletion the callback to invoked on completion
-		 * @return this builder
+		 * Flush the buffered response stream content to the network.
+		 * @throws IOException in case of I/O errors
 		 */
-		SseBuilder onComplete(Runnable onCompletion);
-	}
+		void flush() throws IOException;
 
+	}
 
 	/**
 	 * Defines the context used during the {@link #writeTo(HttpServletRequest, HttpServletResponse, Context)}.