downloadWithProgress method

@override Stream<int> downloadWithProgress(String url, String targetPath, { String? token, int maxRetries = 10, CancelToken? cancelToken, bool? foreground, })

Downloads a file with progress tracking

Returns a stream of progress percentages (0-100)

Parameters:

• url: Source URL
• targetPath: Destination path
• token: Optional auth token
• maxRetries: Max retry attempts for transient errors (default: 10) Note: Auth errors (401/403/404) fail after 1 attempt regardless of this value
• cancelToken: Optional token for cancellation
• foreground: Android foreground service mode (shows notification, no timeout)
  • null (default): auto-detect based on file size (>500MB = foreground)
  • true: always use foreground
  • false: never use foreground

Throws:

• DownloadCancelledException if cancelled via cancelToken

Example:

final cancelToken = CancelToken();
await for (final progress in downloader.downloadWithProgress(..., cancelToken: cancelToken)) {
  print('Progress: $progress%');
}
// Cancel from elsewhere: cancelToken.cancel('User cancelled');

Implementation

@override
Stream<int> downloadWithProgress(
  String url,
  String targetPath, {
  String? token,
  int maxRetries = 10,
  CancelToken? cancelToken,
  bool? foreground, // Ignored on web - no foreground service concept
}) async* {
  // Check cancellation before starting
  cancelToken?.throwIfCancelled();

  // STREAMING MODE: Use OPFS for large models
  if (webStorageMode == WebStorageMode.streaming) {
    if (opfsService == null) {
      debugPrint('[WARNING] OPFS not available, falling back to cacheApi mode');
      debugPrint('[WARNING] Large models (>2GB) may fail with ArrayBuffer limit');
      debugPrint('[WARNING] Use a browser that supports OPFS (Chrome 86+, Edge 86+, Safari 15.2+)');
      // Fall back to cache API mode
      yield* _downloadToCache(url, targetPath, token: token, cancelToken: cancelToken);
      return;
    }
    yield* _downloadToOPFS(url, targetPath, token: token, cancelToken: cancelToken);
    return;
  }

  // CACHE API / NONE MODES: Use blob URLs
  yield* _downloadToCache(url, targetPath, token: token, cancelToken: cancelToken);
}