Skip to content

Commit 985e184

Browse files
authored
feat(web): emit precache_manifest.json when --web-content-hash is enabled (flutter#192953)
## Description Implements **Phase 3** of Flutter Web Content Hashing (flutter#191916): - **Emit `build/web/precache_manifest.json` when `--web-content-hash` is enabled**: - Generated inside `WebServiceWorker.build` (`packages/flutter_tools/lib/src/web/content_hash.dart`) after `hashWebAssets` rewrites hashed assets. - Emits `{ "version": 1, "entries": [...] }` sorted lexicographically by `"url"` for deterministic output. - Each entry includes: - `"url"`: POSIX path relative to `build/web/` - `"hash"`: 8-character lowercase hex SHA-256 prefix of the file's bytes - `"size"`: File byte length (`int`) - `"urlHashed"`: `bool` (`true` if the filename already contains `.$hash.` or ends with `.$hash` so custom service workers/PWAs can skip redundant `?v=<hash>` cache-busting query parameters; `false` for fixed-URL files such as `index.html`, `flutter_bootstrap.js`, `assets/AssetManifest.bin`, `assets/FontManifest.json`, `assets/NOTICES`, and `version.json`). - **Non-Runtime Bloat Exclusion**: - Excludes source maps (`*.map`), symbols (`*.symbols`), compiler info (`*.info.json`), dotfiles (`.` prefix), `flutter_service_worker.js`, `precache_manifest.json` itself, and `canvaskit/**` (unless `kUseLocalCanvasKitFlag == 'true'` / `--no-web-resources-cdn`). - **Stale Manifest Cleanup & Depfile Safety**: - Deletes any stale `precache_manifest.json` in `build/web/` when `--web-content-hash` is `false`. - Excludes `precache_manifest.json` from `WebServiceWorker` input discovery while registering it as a `Depfile` output to prevent input/output cycles in `service_worker.d`. - **Preserve `hide: true` on `--web-content-hash`**: - Keeps `hide: true` on `WebOptions.webContentHash` while runtime raw-key asset resolution (`rootBundle.load`, `ui_web.AssetManager.getAssetUrl`) is completed in companion tasks, and updates the `--help` description to clarify that `assets/AssetManifest.bin.json` and `assets/FontManifest.json` must be served with revalidation while they remain unhashed. > [!NOTE] > On `master`, passing the hidden `--web-content-hash` flag currently causes raw-key asset loads (`rootBundle.load(...)`, `vector_graphics`, DOM media plugins) to 404 on cold cache because physical files are content-hashed on disk but runtime resolution has not yet landed. Phase 2.5 will add runtime key-to-hashed asset resolution in the web engine (`ui_web.AssetManager`) before `--web-content-hash` is un-hidden for general use. ## Related Issues - Fixes flutter#191916 - Part of flutter#149031 ## Tests - Added 3 unit tests in `packages/flutter_tools/test/general.shard/build_system/targets/web_test.dart` verifying `precache_manifest.json` schema/sorting/filtering, `kUseLocalCanvasKitFlag == 'true'` inclusion of `canvaskit/`, and stale manifest deletion when `webContentHash: false`.
1 parent 124f1de commit 985e184

4 files changed

Lines changed: 303 additions & 10 deletions

File tree

‎packages/flutter_tools/lib/src/build_system/targets/web.dart‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1532,12 +1532,21 @@ class WebServiceWorker extends Target {
15321532
.where(
15331533
(File file) =>
15341534
!file.path.endsWith('flutter_service_worker.js') &&
1535+
!file.path.endsWith(kPrecacheManifestFile) &&
15351536
!environment.fileSystem.path.basename(file.path).startsWith('.'),
15361537
)
15371538
.toList();
15381539

1540+
final bool webContentHash = compileConfigs.any(
1541+
(WebCompilerConfig config) => config.webContentHash,
1542+
);
1543+
final File? precacheManifestFile = updatePrecacheManifest(
1544+
environment.outputDir,
1545+
enabled: webContentHash,
1546+
useLocalCanvasKit: environment.defines[kUseLocalCanvasKitFlag] == 'true',
1547+
);
15391548
final File serviceWorkerFile = environment.outputDir.childFile('flutter_service_worker.js');
1540-
final depfile = Depfile(contents, <File>[serviceWorkerFile]);
1549+
final depfile = Depfile(contents, <File>[serviceWorkerFile, ?precacheManifestFile]);
15411550
final String fileGeneratorsPath = environment.artifacts.getArtifactPath(
15421551
Artifact.flutterToolsFileGenerators,
15431552
);

‎packages/flutter_tools/lib/src/web/content_hash.dart‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,3 +192,89 @@ Map<String, File> hashWebAssets(Directory assetsDir) {
192192

193193
return renamedFileMap;
194194
}
195+
196+
/// The filename of the precache manifest generated for web content hashing.
197+
const String kPrecacheManifestFile = 'precache_manifest.json';
198+
199+
bool _shouldExcludeFromPrecacheManifest({
200+
required String posixUrl,
201+
required String basename,
202+
required List<String> segments,
203+
required bool useLocalCanvasKit,
204+
}) {
205+
if (basename.startsWith('.') ||
206+
posixUrl == kPrecacheManifestFile ||
207+
posixUrl == 'flutter_service_worker.js') {
208+
return true;
209+
}
210+
if (basename.endsWith('.map') ||
211+
basename.endsWith('.symbols') ||
212+
basename.endsWith('.info.json')) {
213+
return true;
214+
}
215+
if (!useLocalCanvasKit && segments.firstOrNull == 'canvaskit') {
216+
return true;
217+
}
218+
return false;
219+
}
220+
221+
/// Writes `precache_manifest.json` in [outputDir] when [enabled] is true, or
222+
/// removes any stale manifest file when [enabled] is false.
223+
File? updatePrecacheManifest(
224+
Directory outputDir, {
225+
required bool enabled,
226+
required bool useLocalCanvasKit,
227+
}) {
228+
final File manifestFile = outputDir.childFile(kPrecacheManifestFile);
229+
if (!enabled) {
230+
if (manifestFile.existsSync()) {
231+
manifestFile.deleteSync();
232+
}
233+
return null;
234+
}
235+
236+
if (!outputDir.existsSync()) {
237+
return null;
238+
}
239+
240+
final FileSystem fileSystem = outputDir.fileSystem;
241+
final List<File> files = outputDir.listSync(recursive: true).whereType<File>().toList();
242+
243+
final entries = <Map<String, Object>>[];
244+
for (final file in files) {
245+
final String relativePath = fileSystem.path.relative(file.path, from: outputDir.path);
246+
final List<String> segments = fileSystem.path.split(relativePath);
247+
final String posixUrl = p.posix.joinAll(segments);
248+
final String basename = segments.last;
249+
250+
if (_shouldExcludeFromPrecacheManifest(
251+
posixUrl: posixUrl,
252+
basename: basename,
253+
segments: segments,
254+
useLocalCanvasKit: useLocalCanvasKit,
255+
)) {
256+
continue;
257+
}
258+
259+
final Uint8List bytes = file.readAsBytesSync();
260+
final String shortHash = crypto.sha256.convert(bytes).toString().substring(0, 8);
261+
final bool urlHashed = basename.contains('.$shortHash.') || basename.endsWith('.$shortHash');
262+
263+
entries.add(<String, Object>{
264+
'url': posixUrl,
265+
'hash': shortHash,
266+
'size': bytes.length,
267+
'urlHashed': urlHashed,
268+
});
269+
}
270+
271+
entries.sort(
272+
(Map<String, Object> a, Map<String, Object> b) =>
273+
(a['url']! as String).compareTo(b['url']! as String),
274+
);
275+
276+
manifestFile.writeAsStringSync(
277+
const JsonEncoder.withIndent(' ').convert(<String, Object>{'version': 1, 'entries': entries}),
278+
);
279+
return manifestFile;
280+
}

‎packages/flutter_tools/lib/src/web/web_options.dart‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -80,19 +80,21 @@ abstract final class WebOptions {
8080
'application.',
8181
);
8282

83-
// Hidden while content hashing is incomplete: only compiled entrypoints are
84-
// hashed today. Un-hide once static assets (flutter/flutter#191915) and the
85-
// service worker precache manifest (flutter/flutter#191916) are also hashed,
86-
// so that enabling the flag covers everything a deploy caches.
83+
// Hidden while content hashing runtime asset resolution is incomplete:
84+
// raw-key asset loads (rootBundle.load) and web media plugins require runtime
85+
// asset manifest resolution in ui_web.AssetManager before enabling the flag
86+
// for general use.
8787
static const webContentHash = FlagOptionDescriptor(
8888
name: 'web-content-hash',
8989
hide: true,
9090
help:
91-
'Include a content hash in the filenames of the compiled web '
92-
'entrypoints (for example, "main.dart.<hash>.js") so that browsers '
93-
'fetch new versions after a deploy instead of serving stale cached '
94-
'files. The web server must still serve "index.html" and '
95-
'"flutter_bootstrap.js" with revalidation (for example, '
91+
'Include a content hash in the filenames of compiled web '
92+
'entrypoints (for example, "main.dart.<hash>.js") and static '
93+
'assets in "assets/", and emit a "precache_manifest.json" file '
94+
'so that browsers and custom service workers fetch new versions '
95+
'after a deploy instead of serving stale cached files. The web '
96+
'server must still serve "index.html", "flutter_bootstrap.js", '
97+
'and asset manifests with revalidation (for example, '
9698
'"Cache-Control: no-cache") for a new deploy to be picked up. '
9799
'Not supported with deferred imports. Custom "index.html" files '
98100
'that reference "main.dart.js" directly, and the deprecated '

‎packages/flutter_tools/test/general.shard/build_system/targets/web_test.dart‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2675,4 +2675,200 @@ flutter:
26752675
expect(configString, contains('"main.dart.89abcdef.wasm":'));
26762676
}),
26772677
);
2678+
2679+
test(
2680+
'WebServiceWorker emits precache_manifest.json and excludes non-runtime bloat when webContentHash is true',
2681+
() => testbed.run(() async {
2682+
final File fileGenerators =
2683+
environment.artifacts.getArtifactPath(Artifact.flutterToolsFileGenerators).isEmpty
2684+
? environment.fileSystem.file('flutter_service_worker.js')
2685+
: environment.fileSystem.file(
2686+
environment.fileSystem.path.join(
2687+
environment.artifacts.getArtifactPath(Artifact.flutterToolsFileGenerators),
2688+
'js',
2689+
'flutter_service_worker.js',
2690+
),
2691+
);
2692+
fileGenerators
2693+
..createSync(recursive: true)
2694+
..writeAsStringSync('// service worker stub');
2695+
2696+
const indexBytes = <int>[1, 2, 3, 4];
2697+
const bootstrapBytes = <int>[5, 6, 7, 8, 9];
2698+
const mainJsBytes = <int>[10, 20, 30, 40, 50, 60];
2699+
const logoBytes = <int>[70, 80, 90];
2700+
const manifestBinBytes = <int>[11, 22, 33];
2701+
const extensionlessAssetBytes = <int>[44, 55, 66];
2702+
2703+
final String indexHash = crypto.sha256.convert(indexBytes).toString().substring(0, 8);
2704+
final String bootstrapHash = crypto.sha256.convert(bootstrapBytes).toString().substring(0, 8);
2705+
final String mainJsHash = crypto.sha256.convert(mainJsBytes).toString().substring(0, 8);
2706+
final String logoHash = crypto.sha256.convert(logoBytes).toString().substring(0, 8);
2707+
final String manifestBinHash = crypto.sha256
2708+
.convert(manifestBinBytes)
2709+
.toString()
2710+
.substring(0, 8);
2711+
final String extensionlessHash = crypto.sha256
2712+
.convert(extensionlessAssetBytes)
2713+
.toString()
2714+
.substring(0, 8);
2715+
2716+
environment.outputDir.childFile('index.html')
2717+
..createSync(recursive: true)
2718+
..writeAsBytesSync(indexBytes);
2719+
environment.outputDir.childFile('flutter_bootstrap.js')
2720+
..createSync(recursive: true)
2721+
..writeAsBytesSync(bootstrapBytes);
2722+
environment.outputDir.childFile('main.dart.$mainJsHash.js')
2723+
..createSync(recursive: true)
2724+
..writeAsBytesSync(mainJsBytes);
2725+
environment.outputDir.childFile('assets/images/logo.$logoHash.png')
2726+
..createSync(recursive: true)
2727+
..writeAsBytesSync(logoBytes);
2728+
environment.outputDir.childFile('assets/AssetManifest.bin')
2729+
..createSync(recursive: true)
2730+
..writeAsBytesSync(manifestBinBytes);
2731+
environment.outputDir.childFile('assets/RAW_DATA.$extensionlessHash')
2732+
..createSync(recursive: true)
2733+
..writeAsBytesSync(extensionlessAssetBytes);
2734+
2735+
// Non-runtime files that must be excluded from precache_manifest.json:
2736+
environment.outputDir.childFile('main.dart.$mainJsHash.js.map')
2737+
..createSync(recursive: true)
2738+
..writeAsStringSync('{}');
2739+
environment.outputDir.childFile('main.dart.wasm.symbols')
2740+
..createSync(recursive: true)
2741+
..writeAsStringSync('symbols');
2742+
environment.outputDir.childFile('main.dart.js.info.json')
2743+
..createSync(recursive: true)
2744+
..writeAsStringSync('{}');
2745+
environment.outputDir.childFile('.last_build_id')
2746+
..createSync(recursive: true)
2747+
..writeAsStringSync('build-id');
2748+
environment.outputDir.childFile('canvaskit/canvaskit.wasm')
2749+
..createSync(recursive: true)
2750+
..writeAsBytesSync(<int>[0, 97, 115, 109]);
2751+
2752+
final target = WebServiceWorker(environment.fileSystem, const <WebCompilerConfig>[
2753+
JsCompilerConfig(webContentHash: true),
2754+
], const NoOpAnalytics());
2755+
await target.build(environment);
2756+
2757+
final File manifestFile = environment.outputDir.childFile('precache_manifest.json');
2758+
expect(manifestFile, exists);
2759+
2760+
final decoded = jsonDecode(manifestFile.readAsStringSync()) as Map<String, Object?>;
2761+
expect(decoded['version'], 1);
2762+
2763+
final entries = decoded['entries']! as List<Object?>;
2764+
expect(entries, <Map<String, Object>>[
2765+
<String, Object>{
2766+
'url': 'assets/AssetManifest.bin',
2767+
'hash': manifestBinHash,
2768+
'size': manifestBinBytes.length,
2769+
'urlHashed': false,
2770+
},
2771+
<String, Object>{
2772+
'url': 'assets/RAW_DATA.$extensionlessHash',
2773+
'hash': extensionlessHash,
2774+
'size': extensionlessAssetBytes.length,
2775+
'urlHashed': true,
2776+
},
2777+
<String, Object>{
2778+
'url': 'assets/images/logo.$logoHash.png',
2779+
'hash': logoHash,
2780+
'size': logoBytes.length,
2781+
'urlHashed': true,
2782+
},
2783+
<String, Object>{
2784+
'url': 'flutter_bootstrap.js',
2785+
'hash': bootstrapHash,
2786+
'size': bootstrapBytes.length,
2787+
'urlHashed': false,
2788+
},
2789+
<String, Object>{
2790+
'url': 'index.html',
2791+
'hash': indexHash,
2792+
'size': indexBytes.length,
2793+
'urlHashed': false,
2794+
},
2795+
<String, Object>{
2796+
'url': 'main.dart.$mainJsHash.js',
2797+
'hash': mainJsHash,
2798+
'size': mainJsBytes.length,
2799+
'urlHashed': true,
2800+
},
2801+
]);
2802+
2803+
final File serviceWorkerDepfile = environment.buildDir.childFile('service_worker.d');
2804+
expect(serviceWorkerDepfile, exists);
2805+
expect(serviceWorkerDepfile.readAsStringSync(), contains('precache_manifest.json:'));
2806+
}),
2807+
);
2808+
2809+
test(
2810+
'WebServiceWorker includes canvaskit in precache_manifest.json when kUseLocalCanvasKitFlag is true',
2811+
() => testbed.run(() async {
2812+
environment.defines[kUseLocalCanvasKitFlag] = 'true';
2813+
final File fileGenerators = environment.fileSystem.file(
2814+
environment.fileSystem.path.join(
2815+
environment.artifacts.getArtifactPath(Artifact.flutterToolsFileGenerators),
2816+
'js',
2817+
'flutter_service_worker.js',
2818+
),
2819+
);
2820+
fileGenerators
2821+
..createSync(recursive: true)
2822+
..writeAsStringSync('// service worker stub');
2823+
2824+
const wasmBytes = <int>[0, 97, 115, 109];
2825+
final String wasmHash = crypto.sha256.convert(wasmBytes).toString().substring(0, 8);
2826+
environment.outputDir.childFile('canvaskit/canvaskit.wasm')
2827+
..createSync(recursive: true)
2828+
..writeAsBytesSync(wasmBytes);
2829+
2830+
final target = WebServiceWorker(environment.fileSystem, const <WebCompilerConfig>[
2831+
JsCompilerConfig(webContentHash: true),
2832+
], const NoOpAnalytics());
2833+
await target.build(environment);
2834+
2835+
final File manifestFile = environment.outputDir.childFile('precache_manifest.json');
2836+
final decoded = jsonDecode(manifestFile.readAsStringSync()) as Map<String, Object?>;
2837+
expect(decoded['entries'], <Map<String, Object>>[
2838+
<String, Object>{
2839+
'url': 'canvaskit/canvaskit.wasm',
2840+
'hash': wasmHash,
2841+
'size': wasmBytes.length,
2842+
'urlHashed': false,
2843+
},
2844+
]);
2845+
}),
2846+
);
2847+
2848+
test(
2849+
'WebServiceWorker deletes stale precache_manifest.json when webContentHash is false',
2850+
() => testbed.run(() async {
2851+
final File fileGenerators = environment.fileSystem.file(
2852+
environment.fileSystem.path.join(
2853+
environment.artifacts.getArtifactPath(Artifact.flutterToolsFileGenerators),
2854+
'js',
2855+
'flutter_service_worker.js',
2856+
),
2857+
);
2858+
fileGenerators
2859+
..createSync(recursive: true)
2860+
..writeAsStringSync('// service worker stub');
2861+
2862+
final File staleManifest = environment.outputDir.childFile('precache_manifest.json')
2863+
..createSync(recursive: true)
2864+
..writeAsStringSync('{"version":1,"entries":[]}');
2865+
2866+
final target = WebServiceWorker(environment.fileSystem, const <WebCompilerConfig>[
2867+
JsCompilerConfig(),
2868+
], const NoOpAnalytics());
2869+
await target.build(environment);
2870+
2871+
expect(staleManifest, isNot(exists));
2872+
}),
2873+
);
26782874
}

0 commit comments

Comments
 (0)