Add ability to change [FileMode] of the download by introducing [Dio…

dio/lib/dio.dart

@@ -9,6 +9,7 @@ export 'src/adapter.dart';
 export 'src/cancel_token.dart';
 export 'src/dio.dart';
 export 'src/dio_exception.dart';
+export 'src/file_access_mode.dart';
 export 'src/dio_mixin.dart' hide InterceptorState, InterceptorResultType;
 export 'src/form_data.dart';
 export 'src/headers.dart';

dio/lib/src/dio.dart

@@ -5,6 +5,7 @@ import 'cancel_token.dart';
 import 'dio/dio_for_native.dart'
     if (dart.library.js_interop) 'dio/dio_for_browser.dart'
     if (dart.library.html) 'dio/dio_for_browser.dart';
+import 'file_access_mode.dart';
 import 'dio_mixin.dart';
 import 'headers.dart';
 import 'options.dart';
@@ -209,6 +210,9 @@ abstract class Dio {
   /// [deleteOnError] whether delete the file when error occurs.
   /// The default value is [true].
   ///
+  /// [fileAccessMode]
+  /// {@macro dio.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 +246,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 +259,7 @@ abstract class Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode mode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -266,6 +272,7 @@ abstract class Dio {
       deleteOnError: deleteOnError,
       cancelToken: cancelToken,
       data: data,
+      fileAccessMode: mode,
       options: options,
     );
   }

dio/lib/src/dio/dio_for_native.dart

@@ -6,6 +6,7 @@ import '../adapters/io_adapter.dart';
 import '../cancel_token.dart';
 import '../dio.dart';
 import '../dio_exception.dart';
+import '../file_access_mode.dart';
 import '../dio_mixin.dart';
 import '../headers.dart';
 import '../options.dart';
@@ -32,6 +33,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 +97,12 @@ 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.map(
+        write: () => FileMode.write,
+        append: () => FileMode.append,
+      ),
+    );
 
     // Create a Completer to notify the success/error state.
     final completer = Completer<Response>();

dio/lib/src/dio_mixin.dart

@@ -11,6 +11,7 @@ import 'adapter.dart';
 import 'cancel_token.dart';
 import 'dio.dart';
 import 'dio_exception.dart';
+import 'file_access_mode.dart';
 import 'form_data.dart';
 import 'headers.dart';
 import 'interceptors/imply_content_type.dart';
@@ -286,6 +287,7 @@ abstract class DioMixin implements Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    FileAccessMode mode = FileAccessMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     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,

dio/lib/src/file_access_mode.dart

@@ -0,0 +1,26 @@
+/// {@template dio.FileAccessMode}
+///  The file access mode when downloading the file.
+/// - [FileAccessMode.write]: 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
+/// - [FileAccessMode.append]: Mode for opening a file for reading and writing
+///    to the end of it. The file is created if it does not already exist.
+/// {@endtemplate}
+enum FileAccessMode {
+  write,
+  append,
+}
+
+extension FileAccessModeExtension on FileAccessMode {
+  T map<T>({
+    required T Function() write,
+    required T Function() append,
+  }) {
+    switch (this) {
+      case FileAccessMode.write:
+        return write();
+      case FileAccessMode.append:
+        return append();
+    }
+  }
+}

dio_test/lib/src/test/download_tests.dart

@@ -380,6 +380,54 @@ 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;
+        var 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();
+        var 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',
   );

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,