Skip to content

fix(offline): exact-size quota eviction and budgeted manifest sync - #46

Merged
QQSHI13 merged 2 commits into
mainfrom
fix/sw-quota-accuracy
Aug 20, 2026
Merged

fix(offline): exact-size quota eviction and budgeted manifest sync#46
QQSHI13 merged 2 commits into
mainfrom
fix/sw-quota-accuracy

Conversation

@QQSHI13

@QQSHI13 QQSHI13 commented Aug 19, 2026

Copy link
Copy Markdown
Owner

What

The service worker's quota handling used fake sizes everywhere: 5 MiB assumed per evicted entry, a flat 20 MiB free-space margin, and files were recorded as cached even when they were evicted. On small-quota browsers (Safari, iOS) a large site thrashed: the sync downloaded the whole manifest, hit the quota wall, evicted the just-cached files, and marked them cached anyway — leaving offline coverage at a few tail files that were never re-fetched.

Changes

  • cache-manifest.json now ships a sizes map — exact byte count of every built file (docsforge/build.py). Additive; files/version unchanged, so existing SWs and stored previous-files lists stay compatible.
  • Measured evictionmakeSpaceIfNeeded accounts each entry at its actual size (Content-Length, falling back to reading the body) and frees until available + freed covers the required bytes plus a proportional 10%-of-quota margin. No more 5 MiB guess, no more 20 MiB floor.
  • Budget-aware sync — the manifest sync checks storage.estimate() free space and reserves a flat 20 MiB per download (the usage estimate lags behind in-flight writes). Once the budget is exhausted the sync stops instead of downloading files that will only be evicted again; unbudgeted files are cached on demand when visited. A single resource larger than the whole quota is never cached.
  • Truthful tracking — evicted entries are removed from the persisted docsforge-manifest-files list (both during sync and between syncs), so a later sync re-fetches what was actually evicted.

Tests

  • Regression: sizes map present, every manifest key covered, values match the built files on disk.
  • Integration: sizes matches os.path.getsize for a real build.
  • New e2e (Playwright + --quota-override-size-mb): budget test (25 MiB quota → exactly 1 file synced, tracked files all really cached) and eviction test (3 MiB quota, 2×2 MiB assets → LRU evicted with measured accounting, cache within quota, no tracked-but-missing files). Both skip when the override isn't honoured.
  • Note: docsforge/templates/assets/javascripts/bundle.min.js was regenerated by build_frontend.py — semantically identical (esbuild identifier-mangling only), fixing a pre-existing committed-vs-built drift so the frontend parity check stays green.

Changelog: 12.5.5 section (en + zh).

@QQSHI13
QQSHI13 merged commit 51716a6 into main Aug 20, 2026
11 of 12 checks passed
@QQSHI13
QQSHI13 deleted the fix/sw-quota-accuracy branch August 20, 2026 03:13
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