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:

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 response

Errors

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:

See also