Overview

This change introduces a public API for inspecting what assets are available within a Flutter app. Currently, there is no officially-supported way to do this, and some apps--needing this ability--depend on undocumented behavior internal to Flutter.

Example use case

The google_fonts package, when loading a font, first checks if the font is already available in the app. If it is not available, it will load it from fonts.google.com. Code.

Other known use cases:

• Preemptively searching for available shaders and then warming them up via a call over a MethodChannel.
• Dynamically listing assets (and maybe loading) all assets that match some criterion (e.g. are within some arbitrry directory).
• Tests.

Context

Terminology

The asset manifest. The framework, when performing it's first asset load, has to load a file called the asset manifest, which contains information about assets available to the app (e.g. where to find higher-resolution variants of images). This file is created at build time by the tool. It is meant for framework-internal use--but some Flutter apps, including ones internal to google, read the file directly.

Why we should make this change now

#113637 "replaced" the aforementioned asset manifest (hereafter "legacy manifest") with a new one that enables more performant first loads and has a more flexible schema. However, this PR did not remove all references to the legacy manifest file, since doing so would break apps that directly depend on it¹. In addition, g3 Flutter does not yet generate the new asset manifest file, so--when loading an asset--the framework needs to be able to fallback to the legacy manifest file in the event that the new one isn't present (see #114913).

Still, we do ultimately want to get rid of the legacy asset manifest (#114913). Rather than having users migrate to reading a new framework-internal file, we can use this opportunity to introduce a dedicated, publicly-documented API for listing what assets are available. Users can instead migrate to this new API. This results in less hacky user code and also gives Flutter maintainers more freedom/flexibility to change the internals of asset loading without worrying about breaking user code.

Design

We add a new class, AssetManifest, that is responsible for loading and parsing the asset manifest file contents from an AssetBundle by calling loadStructuredBinaryData (and loadStructuredData as a fallback in case only the legacy asset manifest file is available). This loading will invoked via static factory methods (e.g. AssetManifest.loadFromAssetBundle). AssetManifest will expose two instance methods, listAssets and getAssetMetadata.

• Iterable<String> listAssets() will simply enumerate the list of assets in the manifest by their keys. This provides the capability that we know users need.
• Object? getAssetMetadata(String key) will get the value of the manifest entry corresponding to the asset having the given key. This is meant for use by the framework (i.e. for choosing which image asset variants to load). Since this API is public, the return type is intentionally vague to discourage user code from depending on its shape².

Drawbacks

We really want the framework be the only one to ever calling getAssetMetadata. While the return type being vague discourages users from depending on the shape of returned data, it doesn't stop them from inspecting it at runtime and depending on hardcoded object keys. However, there's no clear alternative to having this method. Here's one I can think of: have listAssets (which can be moved to AssetBundle if desired) and the existing image resolution logic both independently load the asset manifest file. The parser they use will be have to be identical, since the first parsed result could be cached within AssetBundle. In addition, both will need to support logic for falling back to the legacy asset manifest, which would be a lot of duplicated (if temporary) code.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.