Skip to content

feat(web): persist the cache in IndexedDB - #547

Open
ben-milanko wants to merge 1 commit into
Baseflow:mainfrom
Railway-Engineering-Solutions:feat/web-indexeddb-persistence
Open

ben-milanko wants to merge 1 commit into
Baseflow:mainfrom
Railway-Engineering-Solutions:feat/web-indexeddb-persistence

Conversation

@ben-milanko

Copy link
Copy Markdown

✨ What kind of change does this PR introduce? (Bug fix, feature, docs update...)

Feature: persistent caching on web, stored in IndexedDB. This is the first of the two pull requests suggested in the review of #504. Request cancellation is in a separate PR.

⤵️ What is the current behavior?

On web the cache is held in memory (MemoryCacheSystem plus NonStoringObjectProvider), so every page reload or browser restart starts with an empty cache (#480, #339, #361, #122).

🆕 What is the new behavior (if this is a feature change)?

  • Cached files and their cache info are stored in IndexedDB. Each cache manager gets its own database, named flutter_cache_manager_<key>.
  • One schema definition is shared by the file store and the cache info repository. A reference-counted connection pool applies it, so close() really closes the connection and blocked upgrades are logged.
  • Files are written in 512 KiB chunks as they download. openRead streams chunk by chunk, exists() uses count(), and length() reads only a small header, so no whole file is held in memory.
  • When the storage quota is reached, the least recently used entries are evicted together with their data chunks, and the failed write is retried once.
  • Transactions request relaxed durability.
  • CacheStore checks existence with await file.exists() on every platform. A file that a concurrent removal already deleted is treated as removed.
  • file_system.dart stays exported.

💥 Does this PR introduce a breaking change?

No API changes. Behaviour on web changes: IndexedDB becomes the default storage. This is documented in the README and the CHANGELOG. Apps that want the previous behaviour can pass fileSystem: MemoryCacheSystem() and repo: NonStoringObjectProvider() to Config. If you would prefer IndexedDB to be opt-in through Config, that is a small change and I'm happy to make it.

🐛 Recommendations for testing

  • flutter test --platform chrome test/web (also passes with --wasm): 19 browser tests covering the repository, chunked file writes and reads, the connection pool and quota eviction.
  • flutter test: 146 VM tests pass.
  • flutter build web --wasm in example/ builds.
  • Manual check: load an image on web, reload the page, and confirm it is served from the cache.

📝 Links to relevant issues/docs

#480, #339, #361, #122. Follows the review of #504.

🤔 Checklist before submitting

  • All projects build
  • Follows style guide lines (code style guide)
  • Relevant documentation was updated
  • Rebased onto current main
  • Version bumped and dated CHANGELOG entry added

On web, files and cache info are now stored in IndexedDB instead of
memory, so the cache survives reloads and browser restarts (Baseflow#480, Baseflow#339,
Baseflow#361, Baseflow#122). This is the new web default and is documented in the
README; MemoryCacheSystem with NonStoringObjectProvider keeps the old
in-memory behavior.

- One shared schema for the file store and the cache info repository,
  applied by a reference-counted connection pool, so close() really
  closes and blocked upgrades are logged.
- Files are written in 512 KiB chunks as they download; openRead
  streams chunks, exists() uses count() and length() reads only the
  header.
- When the quota is reached, least recently used entries are evicted
  together with their data chunks, and the failed write is retried once.
- Transactions request relaxed durability.
- CacheStore checks existence with await file.exists() on every
  platform and treats a file a concurrent removal already deleted as
  removed.
- Browser tests: flutter test --platform chrome test/web (also --wasm).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant