From 519ad8b1ccb9f08209df44d19ad36ddcb5794dfa Mon Sep 17 00:00:00 2001 From: Jonathan Unsworth <17317065+junsworth@users.noreply.github.com> Date: Thu, 22 Oct 2026 12:47:34 +0100 Subject: [PATCH 1/2] fix: wait for cached files to be removed before deleting their cache info The cleanup started removing files without waiting and then deleted the cache info right away, so the cache info could be gone while the files were still on disk. If the app was killed in between, those files were left with nothing referencing them. The cleanup now waits for the file removals first. The cache info of a file that could not be removed is kept, so the next cleanup retries it. --- flutter_cache_manager/CHANGELOG.md | 4 + .../lib/src/cache_store.dart | 28 +++- flutter_cache_manager/pubspec.yaml | 2 +- .../test/cache_store_test.dart | 137 ++++++++++++++++++ 4 files changed, 165 insertions(+), 6 deletions(-) diff --git a/flutter_cache_manager/CHANGELOG.md b/flutter_cache_manager/CHANGELOG.md index 275c791b..b83df808 100644 --- a/flutter_cache_manager/CHANGELOG.md +++ b/flutter_cache_manager/CHANGELOG.md @@ -1,3 +1,7 @@ +## [3.4.7] - 2026-10-28 + +* Fixes the cache cleanup deleting the cache info before the cached files were removed. When the app was killed in between, files stayed on disk with nothing referencing them. The cache info of a file that could not be removed is now kept, so the next cleanup retries it. + ## [3.4.6] - 2026-10-27 * Catches unhandled asynchronous errors when updating cache-hit metadata and during scheduled cleanup in `CacheStore` ([#535](https://github.com/Baseflow/flutter_cache_manager/issues/535)). diff --git a/flutter_cache_manager/lib/src/cache_store.dart b/flutter_cache_manager/lib/src/cache_store.dart index eaf4d189..dd360c35 100644 --- a/flutter_cache_manager/lib/src/cache_store.dart +++ b/flutter_cache_manager/lib/src/cache_store.dart @@ -201,19 +201,37 @@ class CacheStore { final toRemove = []; final provider = await _cacheInfoRepository; + final removals = >[]; + + Future remove(CacheObject cacheObject) async { + try { + await _removeCachedFile(cacheObject, toRemove); + } catch (_) { + // Keep the cache info of a file that could not be removed, so the next + // cleanup tries again instead of leaving the file behind. + toRemove.remove(cacheObject.id); + rethrow; + } + } + final overCapacity = await provider.getObjectsOverCapacity(_capacity); - final futures = []; for (final cacheObject in overCapacity) { - futures.add(_removeCachedFile(cacheObject, toRemove)); + removals.add(remove(cacheObject)); } final oldObjects = await provider.getOldObjects(_maxAge); for (final cacheObject in oldObjects) { - futures.add(_removeCachedFile(cacheObject, toRemove)); + removals.add(remove(cacheObject)); } - await Future.wait(futures); - await provider.deleteAll(toRemove); + try { + await Future.wait(removals); + } finally { + // Only delete the cache info once the files are gone. When the app is + // killed in between, a cache info without a file is cleaned up on the next + // read, but a file without a cache info would never be found again. + await provider.deleteAll(toRemove); + } } Future emptyCache() async { diff --git a/flutter_cache_manager/pubspec.yaml b/flutter_cache_manager/pubspec.yaml index 8456c4b5..c3d22cd7 100644 --- a/flutter_cache_manager/pubspec.yaml +++ b/flutter_cache_manager/pubspec.yaml @@ -1,6 +1,6 @@ name: flutter_cache_manager description: Generic cache manager for flutter. Saves web files on the storages of the device and saves the cache info using sqflite. -version: 3.4.6 +version: 3.4.7 homepage: https://github.com/Baseflow/flutter_cache_manager topics: - cache diff --git a/flutter_cache_manager/test/cache_store_test.dart b/flutter_cache_manager/test/cache_store_test.dart index 91bdf864..fb653d2f 100644 --- a/flutter_cache_manager/test/cache_store_test.dart +++ b/flutter_cache_manager/test/cache_store_test.dart @@ -6,6 +6,8 @@ import 'package:file/memory.dart'; import 'package:flutter_cache_manager/src/cache_store.dart'; import 'package:flutter_cache_manager/src/logger.dart'; import 'package:flutter_cache_manager/src/storage/cache_object.dart'; +import 'package:flutter_cache_manager/src/storage/file_system/file_system.dart' + as cache_file_system; import 'package:flutter_test/flutter_test.dart'; import 'package:mockito/mockito.dart'; @@ -464,6 +466,103 @@ void main() { ).called(1); }); + test( + 'Store should not remove cache info before the cached file is removed', + () async { + var config = createTestConfig(); + var store = CacheStore(config); + store.cleanupRunMinInterval = const Duration(milliseconds: 1); + var file = await config.returnsFile('testimage.png'); + + var cacheObject = CacheObject( + 'baseflow.com/test.png', + relativePath: 'testimage.png', + id: 1, + validTill: clock.now().add(const Duration(days: 7)), + ); + + when( + config.mockRepo.getObjectsOverCapacity(any), + ).thenAnswer((_) => Future.value([])); + when( + config.mockRepo.getOldObjects(any), + ).thenAnswer((_) => Future.value([cacheObject])); + when( + config.mockRepo.get('baseflow.com/test.png'), + ).thenAnswer((_) => Future.value(cacheObject)); + + expect(await store.getFile('baseflow.com/test.png'), isNotNull); + + // From here on, getting to the file takes a while, like a slow disk. + final fileAvailable = Completer(); + store.fileSystem = _DelayedFileSystem( + store.fileSystem, + fileAvailable.future, + ); + + // Give the cleanup time to run. It must not delete the cache info + // while the file is still on disk. + await Future.delayed(const Duration(milliseconds: 50)); + verifyNever(config.mockRepo.deleteAll(any)); + expect(file.existsSync(), isTrue); + + fileAvailable.complete(); + await untilCalled(config.mockRepo.deleteAll(any)); + + expect(file.existsSync(), isFalse); + verify( + config.mockRepo.deleteAll(argThat(contains(cacheObject.id))), + ).called(1); + }, + ); + + test( + 'Store should keep cache info of a file that cannot be removed', + () async { + final fileSystem = _FailingDeleteFileSystem('broken.png'); + final config = createTestConfig(); + final store = CacheStore(config); + store.cleanupRunMinInterval = const Duration(milliseconds: 1); + store.fileSystem = fileSystem; + await fileSystem.createFileWithData('ok.png'); + await fileSystem.createFileWithData('broken.png'); + + final okObject = CacheObject( + 'baseflow.com/ok.png', + relativePath: 'ok.png', + id: 1, + validTill: clock.now().add(const Duration(days: 7)), + ); + final brokenObject = CacheObject( + 'baseflow.com/broken.png', + relativePath: 'broken.png', + id: 2, + validTill: clock.now().add(const Duration(days: 7)), + ); + + when( + config.mockRepo.getObjectsOverCapacity(any), + ).thenAnswer((_) => Future.value([])); + when( + config.mockRepo.getOldObjects(any), + ).thenAnswer((_) => Future.value([okObject, brokenObject])); + when( + config.mockRepo.get('baseflow.com/ok.png'), + ).thenAnswer((_) => Future.value(okObject)); + + // The failed removal is still reported as a logged cleanup failure. + final logger = setUpTestLogger(); + expect(await store.getFile('baseflow.com/ok.png'), isNotNull); + final log = await logger.waitForLog('Failed to cleanup cache'); + expect(log, contains('Cannot delete')); + verify( + config.mockRepo.deleteAll( + argThat(allOf(contains(okObject.id), isNot(contains(2)))), + ), + ).called(1); + }, + ); + test('Store should recheck cache info when file is removed', () async { var config = createTestConfig(); var store = CacheStore(config); @@ -624,3 +723,41 @@ TestCacheLogger setUpTestLogger() { addTearDown(() => cacheLogger = originalLogger); return testLogger; } + +/// A file system that only hands out files once [_available] has completed. +class _DelayedFileSystem extends cache_file_system.FileSystem { + _DelayedFileSystem(this._inner, this._available); + + final cache_file_system.FileSystem _inner; + final Future _available; + + @override + Future createFile(String name) async { + await _available; + return _inner.createFile(name); + } +} + +/// A file system in which deleting the file called [undeletableName] fails. +class _FailingDeleteFileSystem extends cache_file_system.FileSystem { + _FailingDeleteFileSystem(String undeletableName) + : _fileSystem = MemoryFileSystem( + opHandle: (path, operation) { + if (operation == FileSystemOp.delete && + path.endsWith(undeletableName)) { + throw FileSystemException('Cannot delete', path); + } + }, + ); + + final MemoryFileSystem _fileSystem; + late final Directory _directory = _fileSystem.systemTempDirectory + .createTempSync('test'); + + @override + Future createFile(String name) async => _directory.childFile(name); + + Future createFileWithData(String name) async { + await (await createFile(name)).writeAsBytes([1, 3]); + } +} From 514b20b631de8a6913fd7db69ba22b6a773294e9 Mon Sep 17 00:00:00 2001 From: Jonathan Unsworth <17317065+junsworth@users.noreply.github.com> Date: Fri, 30 Oct 2026 08:44:10 +0000 Subject: [PATCH 2/2] fix: keep cache info only of files that could not be removed Move the partial-failure handling into _removeCachedFile so cleanup, emptyCache and removeCachedFile all delete the cache info of removed files and keep only the failed one. A failing deleteAll is logged instead of replacing the file removal error. --- flutter_cache_manager/CHANGELOG.md | 2 +- .../lib/src/cache_store.dart | 112 ++++++++++++------ .../test/cache_store_test.dart | 95 ++++++++++++++- 3 files changed, 171 insertions(+), 38 deletions(-) diff --git a/flutter_cache_manager/CHANGELOG.md b/flutter_cache_manager/CHANGELOG.md index b83df808..5003cb06 100644 --- a/flutter_cache_manager/CHANGELOG.md +++ b/flutter_cache_manager/CHANGELOG.md @@ -1,6 +1,6 @@ ## [3.4.7] - 2026-10-28 -* Fixes the cache cleanup deleting the cache info before the cached files were removed. When the app was killed in between, files stayed on disk with nothing referencing them. The cache info of a file that could not be removed is now kept, so the next cleanup retries it. +* Keeps cache cleanup going when a cached file cannot be deleted: the cache info of the other removed files is still deleted, and only the failed file's cache info is kept so the next cleanup retries it. ## [3.4.6] - 2026-10-27 diff --git a/flutter_cache_manager/lib/src/cache_store.dart b/flutter_cache_manager/lib/src/cache_store.dart index dd360c35..67fad4c8 100644 --- a/flutter_cache_manager/lib/src/cache_store.dart +++ b/flutter_cache_manager/lib/src/cache_store.dart @@ -198,52 +198,48 @@ class CacheStore { } Future _cleanupCache() async { - final toRemove = []; + final started = {}; + final removed = []; final provider = await _cacheInfoRepository; - final removals = >[]; - Future remove(CacheObject cacheObject) async { - try { - await _removeCachedFile(cacheObject, toRemove); - } catch (_) { - // Keep the cache info of a file that could not be removed, so the next - // cleanup tries again instead of leaving the file behind. - toRemove.remove(cacheObject.id); - rethrow; - } - } - final overCapacity = await provider.getObjectsOverCapacity(_capacity); for (final cacheObject in overCapacity) { - removals.add(remove(cacheObject)); + removals.add( + _removeCachedFile(cacheObject, started: started, removed: removed), + ); } final oldObjects = await provider.getOldObjects(_maxAge); for (final cacheObject in oldObjects) { - removals.add(remove(cacheObject)); + removals.add( + _removeCachedFile(cacheObject, started: started, removed: removed), + ); } - try { - await Future.wait(removals); - } finally { - // Only delete the cache info once the files are gone. When the app is - // killed in between, a cache info without a file is cleaned up on the next - // read, but a file without a cache info would never be found again. - await provider.deleteAll(toRemove); - } + await _deleteCacheInfoOfRemoved( + provider: provider, + removals: removals, + removed: removed, + ); } Future emptyCache() async { final provider = await _cacheInfoRepository; - final toRemove = []; + final started = {}; + final removed = []; final allObjects = await provider.getAllObjects(); - var futures = []; + final removals = >[]; for (final cacheObject in allObjects) { - futures.add(_removeCachedFile(cacheObject, toRemove)); + removals.add( + _removeCachedFile(cacheObject, started: started, removed: removed), + ); } - await Future.wait(futures); - await provider.deleteAll(toRemove); + await _deleteCacheInfoOfRemoved( + provider: provider, + removals: removals, + removed: removed, + ); } void emptyMemoryCache() { @@ -252,18 +248,61 @@ class CacheStore { Future removeCachedFile(CacheObject cacheObject) async { final provider = await _cacheInfoRepository; - final toRemove = []; - await _removeCachedFile(cacheObject, toRemove); - await provider.deleteAll(toRemove); + final removed = []; + final removal = _removeCachedFile( + cacheObject, + started: {}, + removed: removed, + ); + await _deleteCacheInfoOfRemoved( + provider: provider, + removals: [removal], + removed: removed, + ); } + /// Waits for [removals] and then deletes the cache info of the files in + /// [removed], even when some removals failed. + Future _deleteCacheInfoOfRemoved({ + required CacheInfoRepository provider, + required List> removals, + required List removed, + }) async { + Object? removalError; + StackTrace? removalStack; + try { + await Future.wait(removals); + } catch (e, s) { + removalError = e; + removalStack = s; + } + + try { + await provider.deleteAll(removed); + } catch (e, s) { + if (removalError == null) rethrow; + cacheLogger.log( + 'CacheStore: Failed to delete cache info with error:\n$e\n$s', + CacheManagerLogLevel.warning, + ); + } + + if (removalError != null) { + Error.throwWithStackTrace(removalError, removalStack!); + } + } + + /// Adds the id to [removed] only once the file is gone, so the cache info of + /// a file that could not be deleted is kept and retried. [started] stops the + /// same object from being removed twice. Future _removeCachedFile( - CacheObject cacheObject, - List toRemove, - ) async { - if (toRemove.contains(cacheObject.id)) return; + CacheObject cacheObject, { + required Set started, + required List removed, + }) async { + final id = cacheObject.id!; + if (!started.add(id)) return; - toRemove.add(cacheObject.id!); if (_memCache.containsKey(cacheObject.key)) { _memCache.remove(cacheObject.key); } @@ -278,6 +317,7 @@ class CacheStore { // File has already been deleted. Do nothing #184 } } + removed.add(id); } bool memoryCacheContainsKey(String key) { diff --git a/flutter_cache_manager/test/cache_store_test.dart b/flutter_cache_manager/test/cache_store_test.dart index fb653d2f..f51a1b79 100644 --- a/flutter_cache_manager/test/cache_store_test.dart +++ b/flutter_cache_manager/test/cache_store_test.dart @@ -557,7 +557,100 @@ void main() { expect(log, contains('Cannot delete')); verify( config.mockRepo.deleteAll( - argThat(allOf(contains(okObject.id), isNot(contains(2)))), + argThat( + allOf(contains(okObject.id), isNot(contains(brokenObject.id))), + ), + ), + ).called(1); + }, + ); + + test( + 'Store should report the file error when deleting the cache info also fails', + () async { + final fileSystem = _FailingDeleteFileSystem('broken.png'); + final config = createTestConfig(); + final store = CacheStore(config); + store.cleanupRunMinInterval = const Duration(milliseconds: 1); + store.fileSystem = fileSystem; + await fileSystem.createFileWithData('ok.png'); + await fileSystem.createFileWithData('broken.png'); + + final okObject = CacheObject( + 'baseflow.com/ok.png', + relativePath: 'ok.png', + id: 1, + validTill: clock.now().add(const Duration(days: 7)), + ); + final brokenObject = CacheObject( + 'baseflow.com/broken.png', + relativePath: 'broken.png', + id: 2, + validTill: clock.now().add(const Duration(days: 7)), + ); + + when( + config.mockRepo.getObjectsOverCapacity(any), + ).thenAnswer((_) => Future.value([])); + when( + config.mockRepo.getOldObjects(any), + ).thenAnswer((_) => Future.value([okObject, brokenObject])); + when( + config.mockRepo.get('baseflow.com/ok.png'), + ).thenAnswer((_) => Future.value(okObject)); + when( + config.mockRepo.deleteAll(any), + ).thenAnswer((_) => Future.error(Exception('database is locked'))); + + final logger = setUpTestLogger(); + expect(await store.getFile('baseflow.com/ok.png'), isNotNull); + + final cleanupLog = await logger.waitForLog('Failed to cleanup cache'); + expect(cleanupLog, contains('Cannot delete')); + final deleteLog = await logger.waitForLog( + 'Failed to delete cache info', + ); + expect(deleteLog, contains('database is locked')); + }, + ); + + test( + 'Store should keep cache info of a file that cannot be removed when emptying cache', + () async { + final fileSystem = _FailingDeleteFileSystem('broken.png'); + final config = createTestConfig(); + final store = CacheStore(config); + store.fileSystem = fileSystem; + await fileSystem.createFileWithData('ok.png'); + await fileSystem.createFileWithData('broken.png'); + + final okObject = CacheObject( + 'baseflow.com/ok.png', + relativePath: 'ok.png', + id: 1, + validTill: clock.now().add(const Duration(days: 7)), + ); + final brokenObject = CacheObject( + 'baseflow.com/broken.png', + relativePath: 'broken.png', + id: 2, + validTill: clock.now().add(const Duration(days: 7)), + ); + + when( + config.mockRepo.getAllObjects(), + ).thenAnswer((_) => Future.value([okObject, brokenObject])); + + await expectLater( + store.emptyCache(), + throwsA(isA()), + ); + + verify( + config.mockRepo.deleteAll( + argThat( + allOf(contains(okObject.id), isNot(contains(brokenObject.id))), + ), ), ).called(1); },