supabase / supabase-flutter / 39261126285

92%

Build Type

push

github

Committed by web-flow

Commit Message

feat(storage): resumable uploads with pause, resume and cancel (#1984)

Adds resumable uploads to `supabase_storage` over the tus 1.0 endpoint
(`/upload/resumable`), following the
`storage.file_buckets.resumable_upload` spec from supabase/sdk#278.
Linear: SDK-2276.

```dart
final upload = supabase.storage
    .from('videos')
    .resumableUpload('holiday.mp4', file);
upload.progress.listen((progress) {
  print('${progress.status.name}: ${progress.bytesUploaded}/${progress.totalBytes}');
});
upload.pause();
upload.resume();
final response = await upload.done; // or: await upload.cancel();
```

## API

- `StorageFileApi.resumableUpload(path, File)` and
`resumableUploadBinary(path, Uint8List)` start the upload and return a
`ResumableUpload` right away. Both accept `FileOptions` (content type,
cache control, upsert, metadata) and an optional signed upload `token`.
- `ResumableUpload` has `id` (a UUID), `status`, a `progress` stream
that replays the latest `ResumableUploadProgress` (status, bytes
uploaded, total bytes), `done`, and `pause()`, `resume()` and
`cancel()`.
- After a restart, `SupabaseStorageClient.resumableUploads()` lists the
recorded uploads, `resumeUpload(id, file)` and `resumeUploadBinary(id,
data)` continue one with the same file, and `discardResumableUpload(id)`
terminates and forgets one without the file.
- `ResumableUploadOptions` (on `SupabaseStorageClient` and
`StorageClientOptions`) sets the chunk size (6 MiB by default), retry
delays (`0, 3, 5, 10, 20` s), the retry time budget (120 s) and the
`ResumableUploadStorage` that holds the records.
- `UploadResponse.versionId` carries the `Supabase-Object-Version-Id` a
resumable upload reports.

## Behavior

- Every chunk is sent from the offset the server confirmed. `pause()`
aborts the chunk in flight, and `resume()` starts with a `HEAD`. A 409
on a `PATCH` re-reads the offset.
- These count as retries: transport failures, HTTP 408, 429 and 5xx, and
offset conflicts. Retries are limited... (continued)

Coverage Stats

391 of 435 new or added lines in 9 files covered. (89.89%)

2 existing lines in 1 file now uncovered.

10056 of 10926 relevant lines covered (92.04%)

5.43 hits per line