
# 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](downloads.md) is simpler and adds ranges and caching. For a series of messages, use [server-sent events](sse.md).

## Example

```dart
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](sse.md), 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-Type` of a `ResponseEntity` when it has one, else the first type of the mapping's `produces`, else `application/octet-stream`.
- **Status:** `200`, the `@ResponseStatus` of the method, or the status of the `ResponseEntity`.
- **No `Content-Length`:** the size is not known in advance, so the body is sent with chunked transfer encoding.
- **No conditional answers:** a `ResponseEntity` of a streamed body is not checked against `If-None-Match` or `If-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, each `flush` sending what was compressed so far. See [Compression](../server/compression.md).
- **`server.request-timeout`** does not cut a streamed body: the response leaves the request's deadline as soon as it starts. See [Timeouts](../server/timeouts.md).
- **`HEAD`** runs the writer as for a `GET`, and drops what it writes.

## Errors

- **An exception before anything was written** (the method throws, or `writeTo` throws before its first write) is answered like any other: an `@ExceptionHandler` or a `ProblemDetail`. See [Errors](../errors/index.md).
- **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 `flush` or `addStream` fails and `writeTo` ends with that error, which is logged in the same way. Await `flush` regularly, so a long export notices this and stops its work early.

## In Spring (Java)

```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 `ResponseBodySink` with `write(String)` and an awaitable `flush()`, not an `OutputStream`.
- Spring MVC has no byte-stream result type. A declared `Stream<Uint8List>` here is written like WebFlux writes a `Flux<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.

## See also

- [Downloads](downloads.md)
- [Server-sent events](sse.md)
- [Results](../controllers/results.md)
- [Compression](../server/compression.md)
