Skip to content

Commit 48aa011

Browse files
committed
[flutter_tools] Support LocalArtifactDependency and per-extension content-addressed artifact cache layout
Convert `ArtifactDependency` in `package:flutter_tools_core` into a sealed class hierarchy with `RemoteArtifactDependency` (`ArtifactDependency.remote`) and `LocalArtifactDependency` (`ArtifactDependency.local`), including `type` JSON discrimination and `file:` URI validation for `localUri` and optional `stampUri`. Update `ExtensionArtifactManager` to resolve `LocalArtifactDependency` directly on disk (validating `localUri` and `stampUri` existence), cache `RemoteArtifactDependency` downloads under `<sharedRoot>/<extensionName>/<sha256>/<name>` using `$DART_DATA_HOME/flutter_tool_extensions/artifacts` or `$HOME/.flutter_tool_extensions/artifacts`, and guard concurrent downloads with in-process future deduplication and cross-process `FileSystem.runLocked`. Part of flutter#190755 Part of flutter#190751
1 parent c880a50 commit 48aa011

9 files changed

Lines changed: 831 additions & 306 deletions

File tree

‎packages/flutter_tools/lib/src/experimental/extension_artifact_manager.dart‎

Lines changed: 107 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,9 @@ class ExtensionArtifactManager {
5151
final Directory? _cacheDir;
5252
final HttpClient _httpClient;
5353

54-
/// Tracks in-flight download futures keyed by `<extensionName>/<engineVersion>/<artifactName>`
55-
/// to deduplicate concurrent artifact requests within the same process.
54+
/// Tracks in-flight download futures keyed by destination path
55+
/// (`<cacheDir>/<extensionName>/<sha256>/<artifactName>`) to deduplicate
56+
/// concurrent artifact requests within the same process.
5657
final _inFlightDownloads = <String, Future<String>>{};
5758

5859
/// The current Flutter engine revision from the tool cache, or
@@ -70,8 +71,9 @@ class ExtensionArtifactManager {
7071
/// 3. `%LOCALAPPDATA%\flutter_tool_extensions\artifacts` (or
7172
/// `%USERPROFILE%\.flutter_tool_extensions\artifacts`) on Windows, or
7273
/// `$HOME/.flutter_tool_extensions/artifacts` on POSIX platforms.
73-
/// 4. `<systemTempDirectory>/.flutter_tool_extensions/artifacts` if no home
74-
/// environment variable is set.
74+
///
75+
/// Throws a [ToolExit] if no cache directory override or home/data
76+
/// environment variable is available.
7577
Directory get artifactsCacheDirectory {
7678
if (_cacheDir case final Directory dir) {
7779
return dir;
@@ -107,51 +109,51 @@ class ExtensionArtifactManager {
107109
fs.path.join(home.trim(), _hiddenExtensionsCacheDirName, _artifactsCacheSubdirName),
108110
);
109111
}
110-
return fs.systemTempDirectory
111-
.childDirectory(_hiddenExtensionsCacheDirName)
112-
.childDirectory(_artifactsCacheSubdirName);
112+
throwToolExit(
113+
'Unable to determine shared cache directory for tool extension artifacts: '
114+
'none of $_dartDataHomeEnvKey, $_homeEnvKey, $_localAppDataEnvKey, or $_userProfileEnvKey are set.',
115+
);
113116
}
114117

115-
/// Returns the cache directory `<cacheDir>/<extensionName>/<engineVersion>`
116-
/// for the given [extensionName] and [engineVersion].
118+
/// Returns the content-addressed cache directory
119+
/// `<cacheDir>/<extensionName>/<sha256>` for the given [extensionName] and
120+
/// lowercase [sha256] digest.
117121
///
118-
/// Throws an [ArgumentError] if [extensionName] or [engineVersion] is not a
119-
/// valid single path segment.
120-
Directory artifactDirectory({required String engineVersion, required String extensionName}) {
122+
/// Throws an [ArgumentError] if [extensionName] or [sha256] is not a valid
123+
/// single path segment.
124+
Directory artifactDirectory({required String extensionName, required String sha256}) {
121125
if (!ArtifactDependency.isValidSinglePathSegment(extensionName)) {
122126
throw ArgumentError.value(
123127
extensionName,
124128
'extensionName',
125129
'Must be a valid single path segment.',
126130
);
127131
}
128-
if (!ArtifactDependency.isValidSinglePathSegment(engineVersion)) {
129-
throw ArgumentError.value(
130-
engineVersion,
131-
'engineVersion',
132-
'Must be a valid single path segment.',
133-
);
132+
final String normalizedSha256 = sha256.toLowerCase();
133+
if (!ArtifactDependency.isValidSinglePathSegment(normalizedSha256)) {
134+
throw ArgumentError.value(sha256, 'sha256', 'Must be a valid single path segment.');
134135
}
135-
return artifactsCacheDirectory.childDirectory(extensionName).childDirectory(engineVersion);
136+
return artifactsCacheDirectory.childDirectory(extensionName).childDirectory(normalizedSha256);
136137
}
137138

138139
/// Queries all active extensions implementing [ArtifactService] and ensures
139140
/// required artifacts for the current engine version, host platform, and
140-
/// optional [targetPlatforms] are downloaded and verified in the shared cache.
141+
/// optional [targetPlatforms] are resolved on disk or downloaded and verified
142+
/// in the shared cache.
141143
///
142144
/// When [targetPlatforms] is `null`, artifacts for all target platforms
143145
/// supported by each active extension are requested.
144146
///
145-
/// Returns a map from each downloaded artifact's [ArtifactDependency.name] to
147+
/// Returns a map from each resolved artifact's [ArtifactDependency.name] to
146148
/// its local filesystem path, or an empty map when tool extensions are
147149
/// disabled, extension initialization fails, or no active extension implements
148150
/// [ArtifactService].
149151
///
150152
/// RPC failures when querying an extension's artifact list log a warning and
151-
/// skip that extension, whereas download, extraction, or SHA-256 verification
152-
/// failures throw a [ToolExit].
153+
/// skip that extension, whereas missing local artifacts or download,
154+
/// extraction, or SHA-256 verification failures throw a [ToolExit].
153155
///
154-
/// When [force] is `true`, existing cached artifacts are re-downloaded.
156+
/// When [force] is `true`, existing cached remote artifacts are re-downloaded.
155157
Future<Map<String, String>> ensureArtifactsDownloaded({
156158
bool force = false,
157159
Set<String>? targetPlatforms,
@@ -219,18 +221,23 @@ class ExtensionArtifactManager {
219221
);
220222
continue;
221223
}
222-
resolvedArtifacts[dep.name] = await _ensureArtifactCached(
223-
ext.extensionName,
224-
engineVersion,
225-
dep,
226-
force: force,
227-
);
224+
resolvedArtifacts[dep.name] = switch (dep) {
225+
final LocalArtifactDependency localDep => _resolveLocalArtifact(
226+
ext.extensionName,
227+
localDep,
228+
),
229+
final RemoteArtifactDependency remoteDep => await _ensureRemoteArtifactCached(
230+
ext.extensionName,
231+
remoteDep,
232+
force: force,
233+
),
234+
};
228235
}
229236
}
230237
return resolvedArtifacts;
231238
}
232239

233-
/// Queries [ext] over JSON-RPC via [ArtifactService.downloadArtifactsMethod]
240+
/// Queries [ext] over JSON-RPC via [ArtifactService.listRequiredArtifactsMethod]
234241
/// for the list of [ArtifactDependency] descriptors required for the given
235242
/// [engineVersion], [currentHostPlatform], and optional [targetPlatforms].
236243
///
@@ -246,7 +253,7 @@ class ExtensionArtifactManager {
246253
}) async {
247254
try {
248255
final Object? result = await ext.sendRequest(
249-
ArtifactService.downloadArtifactsMethod,
256+
ArtifactService.listRequiredArtifactsMethod,
250257
params: <String, Object?>{
251258
ArtifactService.engineVersionParam: engineVersion,
252259
ArtifactService.hostPlatformParam: currentHostPlatform.cliName,
@@ -261,65 +268,86 @@ class ExtensionArtifactManager {
261268
}
262269
}
263270

271+
/// Resolves a [LocalArtifactDependency] directly to its unpacked local
272+
/// filesystem path after verifying that [LocalArtifactDependency.localUri]
273+
/// (and optional [LocalArtifactDependency.stampUri]) exist on disk.
274+
///
275+
/// Throws a [ToolExit] if [LocalArtifactDependency.localUri] or a non-null
276+
/// [LocalArtifactDependency.stampUri] does not exist on disk.
277+
String _resolveLocalArtifact(String extensionName, LocalArtifactDependency dep) {
278+
final FileSystem fs = _toolContext.fs;
279+
if (dep.stampUri case final Uri stampUri when !fs.file(stampUri).existsSync()) {
280+
throwToolExit(
281+
'Stamp file for local artifact "${dep.name}" for extension "$extensionName" was not found at "${fs.path.fromUri(stampUri)}".',
282+
);
283+
}
284+
final File file = fs.file(dep.localUri);
285+
if (file.existsSync()) {
286+
return fs.path.normalize(file.path);
287+
}
288+
final Directory dir = fs.directory(dep.localUri);
289+
if (dir.existsSync()) {
290+
return fs.path.normalize(dir.path);
291+
}
292+
throwToolExit(
293+
'Local artifact "${dep.name}" for extension "$extensionName" was not found at "${fs.path.fromUri(dep.localUri)}".',
294+
);
295+
}
296+
264297
/// Ensures [dep] is present and verified in the local cache under
265-
/// `<cacheDir>/<extensionName>/<engineVersion>/<dep.name>`, deduplicating
266-
/// concurrent in-process requests via [_inFlightDownloads].
267-
Future<String> _ensureArtifactCached(
298+
/// `<cacheDir>/<extensionName>/<sha256>/<dep.name>`, deduplicating
299+
/// concurrent in-process requests per destination via [_inFlightDownloads].
300+
Future<String> _ensureRemoteArtifactCached(
268301
String extensionName,
269-
String engineVersion,
270-
ArtifactDependency dep, {
302+
RemoteArtifactDependency dep, {
271303
required bool force,
272304
}) async {
273-
final cacheKey = '$extensionName/$engineVersion/${dep.name}';
274-
if (_inFlightDownloads[cacheKey] case final Future<String> existing) {
305+
final Directory destDir = artifactDirectory(extensionName: extensionName, sha256: dep.sha256);
306+
final String destinationPath = destDir.fileSystem.path.join(destDir.path, dep.name);
307+
if (_inFlightDownloads[destinationPath] case final Future<String> existing) {
275308
return existing;
276309
}
277310

278311
final Future<String> downloadFuture = _downloadAndVerifyArtifact(
279-
extensionName,
280-
engineVersion,
281-
dep,
312+
dep: dep,
313+
destDir: destDir,
314+
extensionName: extensionName,
282315
force: force,
283316
);
284-
_inFlightDownloads[cacheKey] = downloadFuture;
317+
_inFlightDownloads[destinationPath] = downloadFuture;
285318
try {
286319
return await downloadFuture;
287320
} finally {
288-
unawaited(_inFlightDownloads.remove(cacheKey));
321+
unawaited(_inFlightDownloads.remove(destinationPath));
289322
}
290323
}
291324

292-
/// Downloads, verifies, and installs [dep] into the `<extensionName>/<engineVersion>`
293-
/// cache directory, returning the local filesystem path to the cached file or
294-
/// extracted directory.
325+
/// Downloads, verifies, and installs [dep] into [destDir]
326+
/// (`<cacheDir>/<extensionName>/<sha256>`), returning the local filesystem
327+
/// path to the cached file or extracted directory.
295328
///
296329
/// Uses a fast unlocked check first (`_isArtifactCachedAndVerified`) when
297330
/// [force] is `false`. If a download is needed, acquires a cross-process file
298-
/// lock (`.${dep.name}.lock` via `fs.runLocked`), re-checks the cache
299-
/// inside the lock, downloads to a temporary staging directory, verifies the
300-
/// SHA-256 checksum, and installs the artifact followed by its `.sha256`
301-
/// stamp file.
302-
Future<String> _downloadAndVerifyArtifact(
303-
String extensionName,
304-
String engineVersion,
305-
ArtifactDependency dep, {
331+
/// lock (`<destDir>.lock` via `fs.runLocked`), re-checks the cache inside the
332+
/// lock, downloads to a temporary staging directory, verifies the SHA-256
333+
/// checksum, and installs the artifact followed by its `.sha256` stamp file.
334+
Future<String> _downloadAndVerifyArtifact({
335+
required RemoteArtifactDependency dep,
336+
required Directory destDir,
337+
required String extensionName,
306338
required bool force,
307339
}) async {
308340
final ToolContext(:FileSystem fs, :Logger logger, :OperatingSystemUtils os) = _toolContext;
309-
final Directory engineDir = artifactDirectory(
310-
engineVersion: engineVersion,
311-
extensionName: extensionName,
312-
);
313-
final File artifactFile = engineDir.childFile(dep.name);
314-
final Directory artifactDir = engineDir.childDirectory(dep.name);
315-
final File stampFile = engineDir.childFile('.${dep.name}$_sha256StampSuffix');
316-
final File lockFile = engineDir.childFile('.${dep.name}$_lockFileSuffix');
341+
final File artifactFile = destDir.childFile(dep.name);
342+
final Directory artifactDir = destDir.childDirectory(dep.name);
343+
final File stampFile = destDir.childFile('.${dep.name}$_sha256StampSuffix');
344+
final File lockFile = fs.file('${destDir.path}$_lockFileSuffix');
317345
final bool isZip = dep.isZipArchive;
318346
final String resolvedPath = isZip ? artifactDir.path : artifactFile.path;
319347

320348
if (!force &&
321349
_isArtifactCachedAndVerified(
322-
engineDir,
350+
destDir,
323351
dep,
324352
deleteStaleOnMismatch: false,
325353
extensionName: extensionName,
@@ -328,14 +356,14 @@ class ExtensionArtifactManager {
328356
return resolvedPath;
329357
}
330358

331-
engineDir.createSync(recursive: true);
359+
destDir.createSync(recursive: true);
332360
await fs.runLocked<void>(
333361
lockPath: lockFile.path,
334362
logger: logger,
335363
scope: () async {
336364
if (!force &&
337365
_isArtifactCachedAndVerified(
338-
engineDir,
366+
destDir,
339367
dep,
340368
deleteStaleOnMismatch: true,
341369
extensionName: extensionName,
@@ -344,7 +372,7 @@ class ExtensionArtifactManager {
344372
return;
345373
}
346374

347-
final Directory stagingDir = engineDir.createTempSync('.tmp_${dep.name}_');
375+
final Directory stagingDir = destDir.createTempSync('.tmp_${dep.name}_');
348376
final File stagingFile = stagingDir.childFile(dep.name);
349377

350378
final Status status = logger.startProgress(
@@ -379,24 +407,24 @@ class ExtensionArtifactManager {
379407
return resolvedPath;
380408
}
381409

382-
/// Checks whether [dep] is already cached in [versionDir] and its `.sha256`
383-
/// stamp file matches [ArtifactDependency.sha256].
410+
/// Checks whether [dep] is already cached in [destDir] and its `.sha256`
411+
/// stamp file matches [RemoteArtifactDependency.sha256].
384412
///
385413
/// When [deleteStaleOnMismatch] is `true` (inside the cross-process lock),
386414
/// deletes any stale cached file/directory and stamp file if the stamp does
387-
/// not match [ArtifactDependency.sha256].
415+
/// not match [RemoteArtifactDependency.sha256].
388416
bool _isArtifactCachedAndVerified(
389-
Directory versionDir,
390-
ArtifactDependency dep, {
417+
Directory destDir,
418+
RemoteArtifactDependency dep, {
391419
required bool deleteStaleOnMismatch,
392420
required String extensionName,
393421
required Logger logger,
394422
}) {
395423
final bool isZip = dep.isZipArchive;
396424
final FileSystemEntity target = isZip
397-
? versionDir.childDirectory(dep.name)
398-
: versionDir.childFile(dep.name);
399-
final File stampFile = versionDir.childFile('.${dep.name}$_sha256StampSuffix');
425+
? destDir.childDirectory(dep.name)
426+
: destDir.childFile(dep.name);
427+
final File stampFile = destDir.childFile('.${dep.name}$_sha256StampSuffix');
400428
if (!target.existsSync() || !stampFile.existsSync()) {
401429
return false;
402430
}
@@ -429,13 +457,13 @@ class ExtensionArtifactManager {
429457
return false;
430458
}
431459

432-
/// Streams the artifact from [ArtifactDependency.url] into [stagingFile] while
433-
/// computing its SHA-256 digest incrementally.
460+
/// Streams the artifact from [RemoteArtifactDependency.url] into [stagingFile]
461+
/// while computing its SHA-256 digest incrementally.
434462
///
435463
/// Throws a [ToolExit] if the HTTP request fails or the computed digest does
436464
/// not match [expectedSha].
437465
Future<void> _downloadAndVerifyToStagingFile({
438-
required ArtifactDependency dep,
466+
required RemoteArtifactDependency dep,
439467
required String expectedSha,
440468
required File stagingFile,
441469
}) async {
@@ -484,7 +512,7 @@ Actual: $actualDigest''');
484512
void _installStagedArtifact({
485513
required Directory artifactDir,
486514
required File artifactFile,
487-
required ArtifactDependency dep,
515+
required RemoteArtifactDependency dep,
488516
required String expectedSha,
489517
required bool isZip,
490518
required OperatingSystemUtils os,

0 commit comments

Comments
 (0)