Introducing FileAccessMode for Dio.download (#2281)

Add the ability to change the `FileMode` of the download without altering the default value, which is `FileMode.write`, to make resuming downloads easier to implement by introducing `FileAccessMode` and mapping it to `FileMode` in `DioForNative`. --- Signed-off-by: shehab mohame <[email protected]> Co-authored-by: Alex Li <[email protected]>
cfug · Jan 23, 2025 · 779ccf0 · 779ccf0
1 parent ffa1cc6
commit 779ccf0
Show file tree

Hide file tree

Showing 8 changed files with 81 additions and 2 deletions.
diff --git a/dio/CHANGELOG.md b/dio/CHANGELOG.md
@@ -8,6 +8,7 @@ See the [Migration Guide][] for the complete breaking changes list.**
 - Update comments and strings with `MultipartFile`.
 - Removes redundant warnings when composing request options on Web.
 - Fixes boundary inconsistency in `FormData.clone()`.
+- Support `FileAccessMode` in `Dio.download` and `Dio.downloadUri` to change download file opening mode
 
 ## 5.7.0
 

diff --git a/dio/lib/src/dio.dart b/dio/lib/src/dio.dart
@@ -209,6 +209,9 @@ abstract class Dio {
   /// [deleteOnError] whether delete the file when error occurs.
   /// The default value is [true].
   ///
+  /// [fileAccessMode]
+  /// {@macro dio.options.FileAccessMode}
+  ///
   /// [lengthHeader] : The real size of original file (not compressed).
   /// When file is compressed:
   /// 1. If this value is 'content-length', the `total` argument of
@@ -242,6 +245,7 @@ abstract class Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -254,6 +258,7 @@ abstract class Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -266,6 +271,7 @@ abstract class Dio {
       deleteOnError: deleteOnError,
       cancelToken: cancelToken,
       data: data,
+      fileAccessMode: fileAccessMode,
       options: options,
     );
   }

diff --git a/dio/lib/src/dio/dio_for_native.dart b/dio/lib/src/dio/dio_for_native.dart
@@ -32,6 +32,7 @@ class DioForNative with DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -95,7 +96,11 @@ class DioForNative with DioMixin implements Dio {
     // Shouldn't call file.writeAsBytesSync(list, flush: flush),
     // because it can write all bytes by once. Consider that the file is
     // a very big size (up to 1 Gigabytes), it will be expensive in memory.
-    RandomAccessFile raf = file.openSync(mode: FileMode.write);
+    RandomAccessFile raf = file.openSync(
+      mode: fileAccessMode == FileAccessMode.write
+          ? FileMode.write
+          : FileMode.append,
+    );
 
     // Create a Completer to notify the success/error state.
     final completer = Completer<Response>();

diff --git a/dio/lib/src/dio_mixin.dart b/dio/lib/src/dio_mixin.dart
@@ -286,6 +286,7 @@ abstract class DioMixin implements Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -298,6 +299,7 @@ abstract class DioMixin implements Dio {
       deleteOnError: deleteOnError,
       cancelToken: cancelToken,
       data: data,
+      fileAccessMode: fileAccessMode,
       options: options,
     );
   }
@@ -310,6 +312,7 @@ abstract class DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,

diff --git a/dio/lib/src/options.dart b/dio/lib/src/options.dart
@@ -753,3 +753,17 @@ class _RequestConfig {
   ResponseDecoder? responseDecoder;
   late ListFormat listFormat;
 }
+
+/// {@template dio.options.FileAccessMode}
+/// The file access mode when downloading a file, corresponds to a subset of
+/// dart:io::[FileMode].
+/// {@endtemplate}
+enum FileAccessMode {
+  /// Mode for opening a file for reading and writing. The file is overwritten
+  /// if it already exists. The file is created if it does not already exist.
+  write,
+
+  /// Mode for opening a file for reading and writing to the end of it.
+  /// The file is created if it does not already exist.
+  append,
+}
diff --git a/dio_test/lib/src/test/download_tests.dart b/dio_test/lib/src/test/download_tests.dart
@@ -380,6 +380,55 @@ void downloadTests(
           completes,
         );
       });
+
+      test('append bytes to previous download', () async {
+        final cancelToken = CancelToken();
+        final path = p.join(tmp.path, 'download_3.txt');
+        final requestedBytes = 1024 * 1024 * 10;
+        int recievedBytes1 = 0;
+        await expectLater(
+          dio.download(
+            '/bytes/$requestedBytes',
+            path,
+            cancelToken: cancelToken,
+            onReceiveProgress: (c, t) {
+              if (c > 5000) {
+                recievedBytes1 = c;
+                cancelToken.cancel();
+              }
+            },
+            deleteOnError: false,
+          ),
+          throwsDioException(
+            DioExceptionType.cancel,
+            stackTraceContains: 'test/download_tests.dart',
+          ),
+        );
+
+        final cancelToken2 = CancelToken();
+        int recievedBytes2 = 0;
+        expectLater(
+          dio.download(
+            '/bytes/$requestedBytes',
+            path,
+            cancelToken: cancelToken,
+            onReceiveProgress: (c, t) {
+              recievedBytes2 = c;
+              if (c > 5000) {
+                cancelToken2.cancel();
+              }
+            },
+            deleteOnError: false,
+            fileAccessMode: FileAccessMode.append,
+          ),
+          throwsDioException(
+            DioExceptionType.cancel,
+            stackTraceContains: 'test/download_tests.dart',
+          ),
+        );
+        await Future.delayed(const Duration(milliseconds: 100), () {});
+        expect(File(path).lengthSync(), recievedBytes1 + recievedBytes2);
+      });
     },
     testOn: 'vm',
   );

diff --git a/plugins/web_adapter/CHANGELOG.md b/plugins/web_adapter/CHANGELOG.md
@@ -1,6 +1,6 @@
 ## Unreleased
 
-*None.*
+- Support `FileAccessMode` in `Dio.download` and `Dio.downloadUri` to change download file opening mode
 
 ## 2.0.0
 

diff --git a/plugins/web_adapter/lib/src/dio_impl.dart b/plugins/web_adapter/lib/src/dio_impl.dart
@@ -22,6 +22,7 @@ class DioForBrowser with DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode fileAccessMode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,