supabase / supabase-flutter / 40927974625

94%

push

github

feat(storage)!: return the response head from downloadStream before the body (#2105)

Resolves SDK-2593.

## What

`downloadStream` used to be an `async*` generator. Nothing was sent
until the stream was listened to, so a missing object or a bad token
arrived as an error on the stream, the status and headers were never
exposed, and a 200 answer to a ranged request threw.

It now returns `Future<StorageDownload>`, following `HttpClientResponse`
in `dart:io` and `StreamedResponse` in `http`:

```dart
final download = await storage.from('videos').downloadStream('a.mp4', range: range);
download.statusCode;    // 200 or 206
download.contentLength; // null when unknown
download.contentRange;
await for (final chunk in download) { ... }
```

- `StorageDownload extends StreamView<Uint8List>`, so `await for`,
`pipe`, `StreamBuilder`, `collectBytes` and `writeToFile` keep working
on it. It exposes `statusCode`, `headers`, `contentLength`,
`contentRange` and `contentType`.
- The future completes once a 2xx response head arrives and reads no
byte of the body. A non-2xx answer is decoded into a
`StorageApiException` and thrown from the future.
- A ranged request answered with a 200 is returned as it is, so the
caller checks `statusCode` before appending to a partial file.
- A failure while the body streams, a timeout included, surfaces on the
stream as a `StorageTransportException`. An abort stays a
`RequestAbortedException`, and an exception thrown by `onProgress`
passes through unchanged.
- Cancelling the subscription closes the connection. `abortSignal`
aborts before the head (it throws from the future) and after it (the
error comes on the stream).
- `contentLength` is `null` for an encoded body, the same rule the
`onProgress` total already used. Both now go through one helper.

The buffered `download(range:)` keeps throwing on a 200, because it
returns only bytes and the caller could not tell the whole object from
the range. The error message now names the requ... (continued)

52 of 52 new or added lines in 3 files covered. (100.0%)

12491 of 13254 relevant lines covered (94.24%)

6.58 hits per line