
# StreamingResponseBody とバイトストリーム

`StreamingResponseBody` は、ハンドラーが少しずつ書き、その間にクライアントが最初の部分をもう受け取っているボディです。`Stream<Uint8List>` または `Stream<List<int>>` を返すと宣言したメソッドは、バイトのチャンクのストリームで同じことを行います。

## 使う理由

大きいボディや作るのに時間がかかるボディがあります。全注文の CSV エクスポート、バックアップ、その場で作る ZIP、プロセスの出力などです。先に全体を作ると、メモリを消費し、クライアントは最初のバイトまで待たされます。作られたそばから書けば:

- サイズに関わらず、メモリ使用量は一定のままです。
- クライアントはすぐに受け取り始めます。
- 遅いクライアントは、バッファーを埋める代わりに、生成側の速度を落とします。

コードがボディを一歩ずつ (行、テキスト、バイト) 書くときは `StreamingResponseBody` を使います。すでにバイトストリーム (ファイルの `openRead()`、`Process.stdout`、Feign クライアントのストリーミングされたレスポンス) があるときは `Stream<Uint8List>` を返します。ディスク上のファイルには [Resource](downloads.md) のほうが簡単で、範囲とキャッシュも加わります。一連のメッセージには [サーバー送信イベント](sse.md) を使ってください。

## 例

```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;

  // 一行ずつ書き、全体をメモリに持つことのない CSV エクスポート。
  @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');
      // 書いたものを送り、出ていくまで待つ。
      await out.flush();
    }
  });

  // 同じものを、ファイル名付きのダウンロードとして。
  @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());

  // ストリームからの生のバイト: `produces` で別の指定がなければ
  // application/octet-stream。
  @GetMapping.of(path: '/backup', produces: 'application/gzip')
  Stream<Uint8List> backup() => File('/var/shop/backup.tar.gz')
      .openRead()
      .map(Uint8List.fromList);

  // ボディの中に別のストリームを加える。
  @GetMapping('/bundle')
  StreamingResponseBody bundle() => StreamingResponseBody((out) async {
    out.add(Uint8List.fromList([0x50, 0x4b]));
    await out.addStream(File('/var/shop/rest.bin').openRead());
  });
}
```

## `StreamingResponseBody`

| メンバー | 型 | 意味 |
|---|---|---|
| `StreamingResponseBody(writeTo)` | コンストラクター | `writeTo` が書くボディ。 |
| `writeTo` | `Future<void> Function(ResponseBodySink out)` | `out` にボディを書く。その `Future` が完了するとレスポンスが終わる。 |

## `ResponseBodySink`

| メンバー | 意味 |
|---|---|
| `add(List<int> bytes)` | ボディにバイトを加える。 |
| `write(String text)` | UTF-8 でエンコードしたテキストを加える。 |
| `Future<void> flush()` | それまでに書いたものをクライアントに送る。さらに書く前に await する。 |
| `Future<void> addStream(Stream<List<int>> stream)` | `stream` のすべてのチャンクを加える。ストリームが終わると完了する。 |

書いたものはバッファーに入ります。`flush` しなければ、バッファーが埋まるかボディが終わるまで、クライアントは何も受け取らないかもしれません。クライアントに進行状況を見せたいときは、論理的なまとまり (行、レコード) ごとに `flush` を呼び、それを await してください。そうすることで、遅いクライアントがあなたのループの速度を落とします。

## バイトストリーム

| 宣言した戻り値の型 | 書き出し方 |
|---|---|
| `Stream<Uint8List>` | 生のバイト。各チャンクを届いたとおりに。 |
| `Stream<List<int>>` | 生のバイト。各チャンクを届いたとおりに。 |
| その他の `Stream<T>` | バイトではなく [サーバー送信イベント](sse.md)。 |
| `ResponseEntity<Stream<Uint8List>>` | エンティティのステータスとヘッダー付きの生のバイト。 |

- **宣言した** 型で決まります。`Stream<Object>` と宣言してバイトのチャンクを返すメソッドは、イベントを書きます。要素の型を正確に宣言してください。
- `Future<Stream<Uint8List>>` を返すメソッドは起動を失敗させます。ストリームそのものを返し、非同期の処理はその中で行ってください (`async*`)。
- ストリームが終わるとレスポンスが終わります。

## レスポンス

- **Content type:** `ResponseEntity` に `Content-Type` があればそれ、なければマッピングの `produces` の最初のタイプ、なければ `application/octet-stream`。
- **ステータス:** `200`、メソッドの `@ResponseStatus`、または `ResponseEntity` のステータス。
- **`Content-Length` なし:** サイズが事前に分からないので、ボディはチャンク形式の転送エンコーディングで送られます。
- **条件付きの応答なし:** ストリーミングされるボディの `ResponseEntity` は、`If-None-Match` や `If-Modified-Since` と照合されません (Spring でも、そうしたボディは届いたとおりに書かれます)。
- **ヘッダーは最初のバイトと一緒に送られます。** ボディが始まる前に (`ResponseEntity` で) すべてのヘッダーを設定してください。その後に作られたセッション Cookie は送られません (警告がログに記録されます)。
- **圧縮:** `server.compression.enabled=true` なら、圧縮対象のタイプのボディは進行に合わせて gzip で圧縮され、各 `flush` がそれまでに圧縮した分を送ります。[圧縮](../server/compression.md) を参照してください。
- **`server.request-timeout`** はストリーミングされるボディを切りません。レスポンスは始まった時点でリクエストの期限から離れます。[タイムアウト](../server/timeouts.md) を参照してください。
- **`HEAD`** は `GET` と同じく書き込み側を実行し、書いたものを破棄します。

## エラー

- **何かを書く前の例外** (メソッドが例外を投げる、または `writeTo` が最初の書き込みの前に例外を投げる) は、他の例外と同じように応答されます。`@ExceptionHandler` または `ProblemDetail` です。[エラー](../errors/index.md) を参照してください。
- **最初のバイトが送られた後の例外:** ステータスは送信済みで変えられません。警告がログに記録され (`Request GET /api/books.csv failed after the response was committed`)、最後のチャンクなしで接続が切断されます。クライアントには完全なレスポンスではなく壊れたレスポンスが見えるので、途中で切れたファイルを完全なものと取り違えることはありません。
- **クライアントが去った:** 接続がなくなっているので、その後の `flush` や `addStream` が失敗し、`writeTo` はそのエラーで終わり、同じようにログに記録されます。定期的に `flush` を await して、長いエクスポートがこれに気づいて早めに処理をやめるようにしてください。

## 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();
    }
  };
}
```

重要な違い:

- シンクは `OutputStream` ではなく、`write(String)` と await できる `flush()` を持つ `ResponseBodySink` です。
- Spring MVC にはバイトストリームの戻り値の型がありません。ここで `Stream<Uint8List>` と宣言したものは、WebFlux が `Flux<DataBuffer>` を書くのと同じように書かれます。
- Spring はボディを非同期スレッドで、非同期リクエストのタイムアウト付きで実行します。ここではリクエスト自身のゾーンで、タイムアウトなしで実行します。

## 関連項目

- [ダウンロード](downloads.md)
- [サーバー送信イベント](sse.md)
- [戻り値](../controllers/results.md)
- [圧縮](../server/compression.md)
