StreamingResponseBody and byte streams
A StreamingResponseBody is a body that the handler writes piece by piece, while the client already receives the first pieces. A method declared to return Stream<Uint8List> or Stream<List<int>> does the same with a stream of byte chunks.
Why
Some bodies are large or slow to make: a CSV export of every order, a backup, a ZIP built on the fly, the output of a process. Building them whole first costs memory and makes the client wait for the first byte. Written as they are produced:
- memory stays flat, whatever the size;
- the client starts receiving at once;
- a slow client slows the producer down instead of filling a buffer.
Use a StreamingResponseBody when your code writes the body step by step (rows, text, bytes). Return a Stream<Uint8List> when you already have a byte stream (a file's openRead(), a Process.stdout, a Feign client's streamed response). For a file on disk, a Resource is simpler and adds ranges and caching. For a series of messages, use server-sent events.
Example
import 'dart:io';
import 'dart:typed_data';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
class Book {
const Book({required this.isbn, required this.title});
final String isbn;
final String title;
}
@Service()
class Books {
Stream<Book> all() => Stream.fromIterable(const [
Book(isbn: '9780441013593', title: 'Dune'),
Book(isbn: '9780553293357', title: 'Foundation'),
]);
}
@RestController()
@RequestMapping('/api')
class ExportController {
ExportController(this.books);
final Books books;
// A CSV export written row by row, never held whole in memory.
@GetMapping.of(path: '/books.csv', produces: 'text/csv')
StreamingResponseBody export() => StreamingResponseBody((out) async {
out.write('isbn,title\n');
await for (final book in books.all()) {
out.write('${book.isbn},${book.title}\n');
// Send what was written, and wait until it is out.
await out.flush();
}
});
// The same, as a download with a file name.
@GetMapping('/books-download.csv')
ResponseEntity<StreamingResponseBody> download() =>
ResponseEntity.status(HttpStatus.ok)
.contentType('text/csv; charset=utf-8')
.header(HttpHeaders.contentDispositionHeader, [
'${const ContentDisposition.attachment(filename: 'books.csv')}',
])
.body(export());
// Raw bytes from a stream: application/octet-stream unless `produces`
// says otherwise.
@GetMapping.of(path: '/backup', produces: 'application/gzip')
Stream<Uint8List> backup() => File('/var/shop/backup.tar.gz')
.openRead()
.map(Uint8List.fromList);
// Another stream added inside a body.
@GetMapping('/bundle')
StreamingResponseBody bundle() => StreamingResponseBody((out) async {
out.add(Uint8List.fromList([0x50, 0x4b]));
await out.addStream(File('/var/shop/rest.bin').openRead());
});
}
StreamingResponseBody
| Member | Type | Meaning |
|---|---|---|
StreamingResponseBody(writeTo) |
constructor | A body written by writeTo. |
writeTo |
Future<void> Function(ResponseBodySink out) |
Writes the body to out. The response ends when its Future completes. |
ResponseBodySink
| Member | Meaning |
|---|---|
add(List<int> bytes) |
Adds bytes to the body. |
write(String text) |
Adds text, encoded as UTF-8. |
Future<void> flush() |
Sends what was written so far to the client. Await it before writing more. |
Future<void> addStream(Stream<List<int>> stream) |
Adds every chunk of stream; completes when the stream is done. |
What you write is buffered. Without flush, the client may get nothing until the buffer fills or the body ends. Call flush after each logical piece (a row, a record) when the client should see progress, and await it: that is how a slow client slows your loop down.
Byte streams
| Declared return type | Written as |
|---|---|
Stream<Uint8List> |
Raw bytes, each chunk as it comes. |
Stream<List<int>> |
Raw bytes, each chunk as it comes. |
Any other Stream<T> |
Server-sent events, not bytes. |
ResponseEntity<Stream<Uint8List>> |
Raw bytes, with the entity's status and headers. |
- The declared type decides. A method declared
Stream<Object>that returns byte chunks writes events. Declare the element type exactly. - A method that returns
Future<Stream<Uint8List>>fails the startup: return the stream itself, and do asynchronous work inside it (async*). - The response ends when the stream is done.
The response
- Content type: the
Content-Typeof aResponseEntitywhen it has one, else the first type of the mapping'sproduces, elseapplication/octet-stream. - Status:
200, the@ResponseStatusof the method, or the status of theResponseEntity. - No
Content-Length: the size is not known in advance, so the body is sent with chunked transfer encoding. - No conditional answers: a
ResponseEntityof a streamed body is not checked againstIf-None-MatchorIf-Modified-Since(as in Spring, where such a body is written as it comes). - The headers go out with the first bytes. Set every header (with a
ResponseEntity) before the body starts. A session cookie created after that is not sent (a warning is logged). - Compression: with
server.compression.enabled=true, a body of a compressed type is gzipped as it goes, eachflushsending what was compressed so far. See Compression. server.request-timeoutdoes not cut a streamed body: the response leaves the request's deadline as soon as it starts. See Timeouts.HEADruns the writer as for aGET, and drops what it writes.
Errors
- An exception before anything was written (the method throws, or
writeTothrows before its first write) is answered like any other: an@ExceptionHandleror aProblemDetail. See Errors. - An exception after the first bytes are out: the status has been sent and cannot change. A warning is logged (
Request GET /api/books.csv failed after the response was committed), and the connection is dropped without the final chunk. The client sees a broken response rather than a complete one, so it does not take a cut file for a whole one. - The client goes away: the connection is gone, so a later
flushoraddStreamfails andwriteToends with that error, which is logged in the same way. Awaitflushregularly, so a long export notices this and stops its work early.
In Spring (Java)
@GetMapping(path = "/api/books.csv", produces = "text/csv")
StreamingResponseBody export() {
return out -> {
for (Book book : books.all()) {
out.write((book.isbn() + "," + book.title() + "\n").getBytes(UTF_8));
out.flush();
}
};
}
Differences that matter:
- The sink is a
ResponseBodySinkwithwrite(String)and an awaitableflush(), not anOutputStream. - Spring MVC has no byte-stream result type. A declared
Stream<Uint8List>here is written like WebFlux writes aFlux<DataBuffer>. - Spring runs the body on an async thread with the async request timeout. Here it runs in the request's own zone, without a timeout.