fix: prevent cache corruption from incomplete files and handle DB async errors

- Atomic file writes: Modified putFile, putFileStream (in cache_manager.dart) and _saveFileAndPostUpdates (in web_helper.dart) to write data into a .tmp file first. The file is only atomically renamed to its final path upon successful completion. This prevents partially written or 0-byte files from lingering if the app is killed, crashes, or runs out of disk space during a write.

- Zero-byte cache protection: Updated _manageResponse (in web_helper.dart) to detect successful downloads that yield 0 bytes (e.g. backend error returning empty body with 200 OK) and delete the file without registering it in the SQLite cache DB.

- FileSystemIO directory optimization: Fixed createFile in ile_system_io.dart to reuse the existing Directory reference instead of creating a new Directory object which was immediately discarded.

- Integrated PR Baseflow#499: Added a catchError block to _getCacheDataFromDatabase(key).then(...) in cache_store.dart. This ensures the Completer resolves properly (with an error) and cleans up _futureCache, preventing a memory leak and a hung Future when DB or FileSystem exceptions occur during data retrieval.

- Integrated PR Baseflow#487: Added an empty file check (length > 0) in json_cache_info_repository.dart before decoding JSON to prevent FormatException crashes when the JSON metadata file is empty (e.g. after a disk full interruption).

- Added comprehensive tests: Covered atomic file operation errors and 0-byte download handling in cache_manager_test.dart and web_helper_test.dart.

Author: Jacek Nowosielski

flutter_cache_manager/lib/src/cache_manager.dart

@@ -87,8 +87,7 @@ class CacheManager implements BaseCacheManager {
   /// cached file is too old the newly downloaded file is returned afterwards.
   @override
   @Deprecated('Prefer to use the new getFileStream method')
-  Stream<FileInfo> getFile(String url,
-      {String? key, Map<String, String>? headers}) {
+  Stream<FileInfo> getFile(String url, {String? key, Map<String, String>? headers}) {
     return getFileStream(
       url,
       key: key,
@@ -108,8 +107,7 @@ class CacheManager implements BaseCacheManager {
   /// returned from the cache there will be no progress given, although the file
   /// might be outdated and a new file is being downloaded in the background.
   @override
-  Stream<FileResponse> getFileStream(String url,
-      {String? key, Map<String, String>? headers, bool withProgress = false}) {
+  Stream<FileResponse> getFileStream(String url, {String? key, Map<String, String>? headers, bool withProgress = false}) {
     key ??= url;
     final streamController = StreamController<FileResponse>();
     _pushFileToStream(streamController, url, key, headers, withProgress);
@@ -132,14 +130,11 @@ class CacheManager implements BaseCacheManager {
         withProgress = false;
       }
     } on Object catch (e) {
-      cacheLogger.log(
-          'CacheManager: Failed to load cached file for $url with error:\n$e',
-          CacheManagerLogLevel.debug);
+      cacheLogger.log('CacheManager: Failed to load cached file for $url with error:\n$e', CacheManagerLogLevel.debug);
     }
     if (cacheFile == null || cacheFile.validTill.isBefore(DateTime.now())) {
       try {
-        await for (final response
-            in _webHelper.downloadFile(url, key: key, authHeaders: headers)) {
+        await for (final response in _webHelper.downloadFile(url, key: key, authHeaders: headers)) {
           if (response is DownloadProgress && withProgress) {
             streamController.add(response);
           }
@@ -148,16 +143,12 @@ class CacheManager implements BaseCacheManager {
           }
         }
       } on Object catch (e) {
-        cacheLogger.log(
-            'CacheManager: Failed to download file from $url with error:\n$e',
-            CacheManagerLogLevel.debug);
+        cacheLogger.log('CacheManager: Failed to download file from $url with error:\n$e', CacheManagerLogLevel.debug);
         if (cacheFile == null && streamController.hasListener) {
           streamController.addError(e);
         }
 
-        if (cacheFile != null &&
-            e is HttpExceptionWithStatus &&
-            e.statusCode == 404) {
+        if (cacheFile != null && e is HttpExceptionWithStatus && e.statusCode == 404) {
           if (streamController.hasListener) {
             streamController.addError(e);
           }
@@ -170,10 +161,7 @@ class CacheManager implements BaseCacheManager {
 
   ///Download the file and add to cache
   @override
-  Future<FileInfo> downloadFile(String url,
-      {String? key,
-      Map<String, String>? authHeaders,
-      bool force = false}) async {
+  Future<FileInfo> downloadFile(String url, {String? key, Map<String, String>? authHeaders, bool force = false}) async {
     key ??= url;
     final fileResponse = await _webHelper
         .downloadFile(
@@ -189,14 +177,11 @@ class CacheManager implements BaseCacheManager {
   /// Get the file from the cache.
   /// Specify [ignoreMemCache] to force a re-read from the database
   @override
-  Future<FileInfo?> getFileFromCache(String key,
-          {bool ignoreMemCache = false}) =>
-      _store.getFile(key, ignoreMemCache: ignoreMemCache);
+  Future<FileInfo?> getFileFromCache(String key, {bool ignoreMemCache = false}) => _store.getFile(key, ignoreMemCache: ignoreMemCache);
 
   ///Returns the file from memory if it has already been fetched
   @override
-  Future<FileInfo?> getFileFromMemory(String key) =>
-      _store.getFileFromMemory(key);
+  Future<FileInfo?> getFileFromMemory(String key) => _store.getFileFromMemory(key);
 
   /// Put a file in the cache. It is recommended to specify the [eTag] and the
   /// [maxAge]. When [maxAge] is passed and the eTag is not set the file will
@@ -228,7 +213,16 @@ class CacheManager implements BaseCacheManager {
     );
 
     final file = await _config.fileSystem.createFile(cacheObject.relativePath);
-    await file.writeAsBytes(fileBytes);
+    final tempFile = file.parent.childFile('${file.basename}.tmp');
+    try {
+      await tempFile.writeAsBytes(fileBytes);
+      await tempFile.rename(file.path);
+    } on Object {
+      try {
+        if (await tempFile.exists()) await tempFile.delete();
+      } catch (_) {}
+      rethrow;
+    }
     _store.putFile(cacheObject);
     return file;
   }
@@ -263,13 +257,17 @@ class CacheManager implements BaseCacheManager {
     );
 
     final file = await _config.fileSystem.createFile(cacheObject.relativePath);
-
-    // Always copy file
-    final sink = file.openWrite();
-    await source
-        // this map is need to map UInt8List to List<int>
-        .map((event) => event)
-        .pipe(sink);
+    final tempFile = file.parent.childFile('${file.basename}.tmp');
+    try {
+      final sink = tempFile.openWrite();
+      await source.map((event) => event).pipe(sink);
+      await tempFile.rename(file.path);
+    } on Object {
+      try {
+        if (await tempFile.exists()) await tempFile.delete();
+      } catch (_) {}
+      rethrow;
+    }
 
     _store.putFile(cacheObject);
     return file;

flutter_cache_manager/lib/src/cache_store.dart

@@ -33,14 +33,12 @@ class CacheStore {
         _cacheInfoRepository = config.repo.open().then((value) => config.repo);
 
   Future<FileInfo?> getFile(String key, {bool ignoreMemCache = false}) async {
-    final cacheObject =
-        await retrieveCacheData(key, ignoreMemCache: ignoreMemCache);
+    final cacheObject = await retrieveCacheData(key, ignoreMemCache: ignoreMemCache);
     if (cacheObject == null) {
       return null;
     }
     final file = await fileSystem.createFile(cacheObject.relativePath);
-    cacheLogger.log(
-        'CacheManager: Loaded $key from cache', CacheManagerLogLevel.verbose);
+    cacheLogger.log('CacheManager: Loaded $key from cache', CacheManagerLogLevel.verbose);
 
     return FileInfo(
       file,
@@ -60,8 +58,7 @@ class CacheStore {
     }
   }
 
-  Future<CacheObject?> retrieveCacheData(String key,
-      {bool ignoreMemCache = false}) async {
+  Future<CacheObject?> retrieveCacheData(String key, {bool ignoreMemCache = false}) async {
     if (!ignoreMemCache && _memCache.containsKey(key)) {
       if (await _fileExists(_memCache[key])) {
         return _memCache[key];
@@ -83,6 +80,9 @@ class CacheStore {
         }
         completer.complete(cacheObject);
         _futureCache.remove(key);
+      }).catchError((Object err) {
+        completer.completeError(err);
+        _futureCache.remove(key);
       });
       _futureCache[key] = completer.future;
     }
@@ -95,16 +95,23 @@ class CacheStore {
       return null;
     }
     final file = await fileSystem.createFile(cacheObject.relativePath);
-    return FileInfo(
-        file, FileSource.Cache, cacheObject.validTill, cacheObject.url);
+    return FileInfo(file, FileSource.Cache, cacheObject.validTill, cacheObject.url);
   }
 
   Future<bool> _fileExists(CacheObject? cacheObject) async {
     if (cacheObject == null) {
       return false;
     }
-    final file = await fileSystem.createFile(cacheObject.relativePath);
-    return file.exists();
+    try {
+      final file = await fileSystem.createFile(cacheObject.relativePath);
+      if (!await file.exists()) return false;
+      // Treat empty files (e.g. from interrupted writes) as missing so
+      // they get re-downloaded instead of failing at decode time.
+      final length = await file.length();
+      return length > 0;
+    } on FileSystemException {
+      return false;
+    }
   }
 
   Future<CacheObject?> _getCacheDataFromDatabase(String key) async {
@@ -172,8 +179,7 @@ class CacheStore {
     await provider.deleteAll(toRemove);
   }
 
-  Future<void> _removeCachedFile(
-      CacheObject cacheObject, List<int> toRemove) async {
+  Future<void> _removeCachedFile(CacheObject cacheObject, List<int> toRemove) async {
     if (toRemove.contains(cacheObject.id)) return;
 
     toRemove.add(cacheObject.id!);

flutter_cache_manager/lib/src/storage/cache_info_repositories/json_cache_info_repository.dart

@@ -20,8 +20,7 @@ class JsonCacheInfoRepository extends CacheInfoRepository
   /// Either the path or the database name should be provided.
   /// If the path is provider it should end with '{databaseName}.json',
   /// for example: /data/user/0/com.example.example/databases/imageCache.json
-  JsonCacheInfoRepository({this.path, this.databaseName})
-      : assert(path == null || databaseName == null);
+  JsonCacheInfoRepository({this.path, this.databaseName}) : assert(path == null || databaseName == null);
 
   /// The directory and the databaseName should both the provided. The database
   /// is stored as {databaseName}.json in the directory,
@@ -137,7 +136,7 @@ class JsonCacheInfoRepository extends CacheInfoRepository
   Future<void> _readFile(File file) async {
     _cacheObjects.clear();
     _jsonCache.clear();
-    if (await file.exists()) {
+    if (await file.exists() && await file.length() > 0) {
       try {
         final jsonString = await file.readAsString();
         final json = jsonDecode(jsonString) as List<dynamic>;

flutter_cache_manager/lib/src/storage/file_system/file_system_io.dart

@@ -6,9 +6,8 @@ import 'package:path_provider/path_provider.dart';
 
 class IOFileSystem implements FileSystem {
   final Future<Directory> _fileDir;
-  final String _cacheKey;
 
-  IOFileSystem(this._cacheKey) : _fileDir = createDirectory(_cacheKey);
+  IOFileSystem(String cacheKey) : _fileDir = createDirectory(cacheKey);
 
   static Future<Directory> createDirectory(String key) async {
     final baseDir = await getTemporaryDirectory();
@@ -24,7 +23,7 @@ class IOFileSystem implements FileSystem {
   Future<File> createFile(String name) async {
     final directory = await _fileDir;
     if (!(await directory.exists())) {
-      await createDirectory(_cacheKey);
+      await directory.create(recursive: true);
     }
     return directory.childFile(name);
   }