Skip to content

Commit 8dbf04f

Browse files
committed
[flutter_tools] Address review comments on ExtensionPackageConfig and ExtensionConnection
- Mark `ExtensionConnection.spawn` as `@visibleForTesting` and suppress the transitional use in `ExtensionManager.initialize()` until flutter#194774. - Add `ExtensionJsonParsing.stringSet` for parsing sets of unique strings, optionally trimming and rejecting empty entries. - Require a non-empty `services` list in `ExtensionPackageConfig`, use `stringSet` for all list fields, accept `Map<String, Object?>` in `fromMap`, and document string identifier conventions. Part of flutter#190755
1 parent 989272c commit 8dbf04f

6 files changed

Lines changed: 225 additions & 42 deletions

File tree

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import 'dart:isolate';
77

88
import 'package:flutter_tools_extension/flutter_tools_extension.dart';
99
import 'package:json_rpc_2/json_rpc_2.dart' as json_rpc;
10+
import 'package:meta/meta.dart';
1011
import 'package:stream_channel/isolate_channel.dart';
1112

1213
import '../base/logger.dart';
@@ -74,6 +75,7 @@ class ExtensionConnection {
7475
/// Used by unit tests to exercise extension protocol behavior in-process
7576
/// without compiling a `.dill` kernel file, and during transitional bootstrap
7677
/// before dynamic project discovery is wired via [spawnUri].
78+
@visibleForTesting
7779
static Future<ExtensionConnection> spawn(
7880
ExtensionEntryPoint entryPoint, {
7981
required Logger logger,

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ class ExtensionManager {
7777
'ExtensionManager initializing for platform "$hostPlatformName" with ${entryPoints.length} entrypoint(s).',
7878
);
7979
for (final entryPoint in entryPoints) {
80+
// ignore: invalid_use_of_visible_for_testing_member // Transitional until #194774.
8081
final ExtensionConnection connection = await ExtensionConnection.spawn(
8182
entryPoint,
8283
logger: _logger,

‎packages/flutter_tools/packages/flutter_tools_core/lib/src/extension_package_config.dart‎

Lines changed: 37 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,26 @@ import 'json_utils.dart';
2929
/// `'bin/<name>.dart'`.
3030
/// - `supported_platforms` (`List<String>`, optional): Host operating systems on
3131
/// which the extension can run (normalized to lowercase, e.g., `'linux'`,
32-
/// `'macos'`, `'windows'`). When omitted or empty, [supportsHostPlatform]
33-
/// imposes no static host platform filter before spawning.
34-
/// - `services` (`List<String>`, optional): RPC service namespaces implemented
32+
/// `'macos'`, `'windows'`). Platform-agnostic extensions omit this field to
33+
/// run on all host platforms (when omitted or empty, [supportsHostPlatform]
34+
/// imposes no static host platform filter before spawning). Extensions with
35+
/// host-specific native tools or dependencies must explicitly declare their
36+
/// supported host operating systems.
37+
/// - `services` (`List<String>`, required): RPC service namespaces implemented
3538
/// by the extension (e.g., `'diagnostics'`, `'config'`, `'template'`,
36-
/// `'device'`, `'build'`).
37-
/// - `build_targets` (`List<String>`, optional): Static top-level `flutter build`
38-
/// subcommand target names contributed by the extension.
39-
/// - `templates` (`List<String>`, optional): Custom project template names
40-
/// contributed by the extension.
39+
/// `'device'`, `'build'`). Required, non-empty. Entries are lowercase service
40+
/// namespace identifiers matching known tool services (`'build'`,
41+
/// `'device'`, `'template'`, `'config'`, `'diagnostics'`, `'clean'`,
42+
/// `'artifacts'`).
43+
/// - `build_targets` (`List<String>`, optional): Lowercase kebab-case
44+
/// subcommand target names contributed to `flutter build` (e.g.
45+
/// `'custom-target'`).
46+
/// - `templates` (`List<String>`, optional): Lowercase kebab-case template
47+
/// names contributed to `flutter create -t` (e.g. `'custom-app'`).
4148
/// - `platforms` (`List<String>`, optional): Custom target platform identifiers
42-
/// supported for `flutter create --platforms=<platform>`. Each entry must
43-
/// match `^[a-z][a-z0-9_]*$`.
49+
/// supported for `flutter create --platforms=<platform>`. Each entry must be
50+
/// a lowercase snake_case identifier starting with a letter and containing
51+
/// only lowercase letters, digits, and underscores (e.g. `'custom_os'`).
4452
///
4553
/// ### Example `extension/flutter_tools/config.yaml`
4654
///
@@ -72,10 +80,11 @@ final class ExtensionPackageConfig {
7280
String? entrypoint,
7381
Iterable<String> platforms = const <String>{},
7482
this.protocolVersion = currentProtocolVersion,
75-
Iterable<String> services = const <String>{},
83+
required Iterable<String> services,
7684
Iterable<String> supportedPlatforms = const <String>{},
7785
Iterable<String> templates = const <String>{},
78-
}) : entrypoint = _validateEntrypoint(entrypoint ?? 'bin/$name.dart'),
86+
}) : assert(services.isNotEmpty),
87+
entrypoint = _validateEntrypoint(entrypoint ?? 'bin/$name.dart'),
7988
supportedPlatforms = Set<String>.unmodifiable(
8089
supportedPlatforms.map((String p) => p.toLowerCase()),
8190
),
@@ -84,11 +93,10 @@ final class ExtensionPackageConfig {
8493
templates = Set<String>.unmodifiable(templates),
8594
platforms = _validatePlatforms(platforms);
8695

87-
/// Parses an [ExtensionPackageConfig] from a decoded YAML or JSON [map].
96+
/// Parses an [ExtensionPackageConfig] from a decoded YAML or JSON [json] map.
8897
///
8998
/// Throws a [FormatException] if required fields are missing or invalid.
90-
factory ExtensionPackageConfig.fromMap(Map<Object?, Object?> map, {String? packageName}) {
91-
final Map<String, Object?> json = map.cast<String, Object?>();
99+
factory ExtensionPackageConfig.fromMap(Map<String, Object?> json, {String? packageName}) {
92100
final String rawName = packageName != null && json[nameKey] == null
93101
? packageName
94102
: json.requiredField<String>(nameKey);
@@ -112,15 +120,22 @@ final class ExtensionPackageConfig {
112120
final String? rawEntrypoint = json.nullableField<String>(entrypointKey);
113121
final String entrypoint = _validateEntrypoint(rawEntrypoint ?? 'bin/$name.dart');
114122

123+
final Set<String> services = json.stringSet(servicesKey, rejectEmpty: true);
124+
if (services.isEmpty) {
125+
throw const FormatException(
126+
'Extension config.yaml must specify a non-empty list of services for "$servicesKey".',
127+
);
128+
}
129+
115130
return ExtensionPackageConfig(
116131
name: name,
117132
protocolVersion: protocolVersion,
118133
entrypoint: entrypoint,
119-
supportedPlatforms: _parseStringSet(json, supportedPlatformsKey),
120-
services: _parseStringSet(json, servicesKey),
121-
buildTargets: _parseStringSet(json, buildTargetsKey),
122-
templates: _parseStringSet(json, templatesKey),
123-
platforms: _parseStringSet(json, platformsKey),
134+
supportedPlatforms: json.stringSet(supportedPlatformsKey, rejectEmpty: true),
135+
services: services,
136+
buildTargets: json.stringSet(buildTargetsKey, rejectEmpty: true),
137+
templates: json.stringSet(templatesKey, rejectEmpty: true),
138+
platforms: json.stringSet(platformsKey, rejectEmpty: true),
124139
);
125140
}
126141

@@ -224,27 +239,15 @@ final class ExtensionPackageConfig {
224239
final String trimmed = platform.trim();
225240
if (!_platformIdentifierPattern.hasMatch(trimmed)) {
226241
throw FormatException(
227-
'Extension config.yaml "$platformsKey" entries must be valid lowercase identifiers, '
228-
'got: "$platform".',
242+
'Extension config.yaml "$platformsKey" entries must be lowercase snake_case identifiers '
243+
'starting with a letter (e.g. "custom_os"), got: "$platform".',
229244
);
230245
}
231246
validated.add(trimmed);
232247
}
233248
return Set<String>.unmodifiable(validated);
234249
}
235250

236-
static Set<String> _parseStringSet(Map<String, Object?> json, String fieldName) {
237-
return <String>{
238-
for (final String item in json.stringIterable(fieldName))
239-
if (item.trim().isNotEmpty)
240-
item.trim()
241-
else
242-
throw FormatException(
243-
'Extension config.yaml "$fieldName" entries must be non-empty strings, got: "$item".',
244-
),
245-
};
246-
}
247-
248251
static const SetEquality<String> _stringSetEquality = SetEquality<String>();
249252

250253
@override

‎packages/flutter_tools/packages/flutter_tools_core/lib/src/json_utils.dart‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,4 +54,27 @@ extension ExtensionJsonParsing on Map<String, Object?> {
5454
),
5555
};
5656
}
57+
58+
/// Extracts an optional set of unique [String]s from this JSON map,
59+
/// returning [defaultValue] if the key is missing or `null`, or throwing
60+
/// a [FormatException] if the value is not an [Iterable], contains
61+
/// non-[String] elements, or contains empty/whitespace-only elements when
62+
/// [rejectEmpty] is `true`.
63+
Set<String> stringSet(
64+
String key, {
65+
Set<String> defaultValue = const <String>{},
66+
bool rejectEmpty = false,
67+
}) {
68+
final Iterable<String> items = stringIterable(key, defaultValue: defaultValue);
69+
if (!rejectEmpty) {
70+
return Set<String>.unmodifiable(items);
71+
}
72+
return Set<String>.unmodifiable(<String>{
73+
for (final String item in items)
74+
if (item.trim().isNotEmpty)
75+
item.trim()
76+
else
77+
throw FormatException('Invalid "$key" element: expected non-empty String, got "$item".'),
78+
});
79+
}
5780
}

‎packages/flutter_tools/packages/flutter_tools_core/test/extension_package_config_test.dart‎

Lines changed: 69 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ void main() {
4242

4343
final String encoded = jsonEncode(map);
4444
final parsed = ExtensionPackageConfig.fromMap(
45-
jsonDecode(encoded) as Map<Object?, Object?>,
45+
jsonDecode(encoded) as Map<String, Object?>,
4646
packageName: 'my_custom_ext',
4747
);
4848
expect(parsed, equals(config));
@@ -54,51 +54,102 @@ void main() {
5454
test('applies default protocolVersion and entrypoint when omitted', () {
5555
final config = ExtensionPackageConfig.fromMap(const <String, Object?>{
5656
ExtensionPackageConfig.nameKey: 'minimal_ext',
57+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
5758
});
5859

5960
expect(config.name, 'minimal_ext');
6061
expect(config.protocolVersion, ExtensionPackageConfig.currentProtocolVersion);
6162
expect(config.entrypoint, 'bin/minimal_ext.dart');
6263
expect(config.supportedPlatforms, isEmpty);
6364
expect(config.supportsHostPlatform('windows'), isTrue);
64-
expect(config.services, isEmpty);
65+
expect(config.services, const <String>{'diagnostics'});
6566
expect(config.buildTargets, isEmpty);
6667
expect(config.templates, isEmpty);
6768
expect(config.platforms, isEmpty);
6869
});
6970

7071
test('falls back to packageName when name key is omitted', () {
71-
final config = ExtensionPackageConfig.fromMap(
72-
const <String, Object?>{},
73-
packageName: 'inferred_ext',
74-
);
72+
final config = ExtensionPackageConfig.fromMap(const <String, Object?>{
73+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
74+
}, packageName: 'inferred_ext');
7575

7676
expect(config.name, 'inferred_ext');
7777
expect(config.entrypoint, 'bin/inferred_ext.dart');
7878
});
7979

80+
test('trims list entries', () {
81+
final config = ExtensionPackageConfig.fromMap(const <String, Object?>{
82+
ExtensionPackageConfig.nameKey: 'my_ext',
83+
ExtensionPackageConfig.servicesKey: <String>[' diagnostics ', 'build'],
84+
ExtensionPackageConfig.platformsKey: <String>[' custom_os '],
85+
});
86+
87+
expect(config.services, const <String>{'diagnostics', 'build'});
88+
expect(config.platforms, const <String>{'custom_os'});
89+
});
90+
91+
test('throws FormatException when services is missing or empty', () {
92+
const servicesError =
93+
'Extension config.yaml must specify a non-empty list of services for '
94+
'"${ExtensionPackageConfig.servicesKey}".';
95+
for (final json in const <Map<String, Object?>>[
96+
<String, Object?>{ExtensionPackageConfig.nameKey: 'my_ext'},
97+
<String, Object?>{
98+
ExtensionPackageConfig.nameKey: 'my_ext',
99+
ExtensionPackageConfig.servicesKey: null,
100+
},
101+
<String, Object?>{
102+
ExtensionPackageConfig.nameKey: 'my_ext',
103+
ExtensionPackageConfig.servicesKey: <String>[],
104+
},
105+
]) {
106+
expect(
107+
() => ExtensionPackageConfig.fromMap(json),
108+
throwsA(
109+
isA<FormatException>().having(
110+
(FormatException e) => e.message,
111+
'message',
112+
servicesError,
113+
),
114+
),
115+
);
116+
}
117+
expect(
118+
() => ExtensionPackageConfig.fromMap(const <String, Object?>{
119+
ExtensionPackageConfig.nameKey: 'my_ext',
120+
ExtensionPackageConfig.servicesKey: <String>['diagnostics', ' '],
121+
}),
122+
throwsFormatException,
123+
);
124+
});
125+
80126
test('throws FormatException on invalid or mismatched fields', () {
81127
expect(
82-
() => ExtensionPackageConfig.fromMap(const <String, Object?>{}),
128+
() => ExtensionPackageConfig.fromMap(const <String, Object?>{
129+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
130+
}),
83131
throwsFormatException,
84132
);
85133
expect(
86134
() => ExtensionPackageConfig.fromMap(const <String, Object?>{
87135
ExtensionPackageConfig.nameKey: 'wrong_name',
136+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
88137
}, packageName: 'expected_name'),
89138
throwsFormatException,
90139
);
91140
expect(
92141
() => ExtensionPackageConfig.fromMap(const <String, Object?>{
93142
ExtensionPackageConfig.nameKey: 'my_ext',
94143
ExtensionPackageConfig.protocolVersionKey: '1',
144+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
95145
}),
96146
throwsFormatException,
97147
);
98148
expect(
99149
() => ExtensionPackageConfig.fromMap(const <String, Object?>{
100150
ExtensionPackageConfig.nameKey: 'my_ext',
101151
ExtensionPackageConfig.entrypointKey: '',
152+
ExtensionPackageConfig.servicesKey: <String>['diagnostics'],
102153
}),
103154
throwsFormatException,
104155
);
@@ -113,6 +164,7 @@ void main() {
113164
() => ExtensionPackageConfig.fromMap(<String, Object?>{
114165
ExtensionPackageConfig.nameKey: 'my_ext',
115166
ExtensionPackageConfig.entrypointKey: invalidEntrypoint,
167+
ExtensionPackageConfig.servicesKey: const <String>['diagnostics'],
116168
}),
117169
throwsFormatException,
118170
);
@@ -127,8 +179,17 @@ void main() {
127179
() => ExtensionPackageConfig.fromMap(<String, Object?>{
128180
ExtensionPackageConfig.nameKey: 'my_ext',
129181
ExtensionPackageConfig.platformsKey: <Object?>[invalidPlatform],
182+
ExtensionPackageConfig.servicesKey: const <String>['diagnostics'],
130183
}),
131-
throwsFormatException,
184+
throwsA(
185+
isA<FormatException>().having(
186+
(FormatException e) => e.message,
187+
'message',
188+
'Extension config.yaml "${ExtensionPackageConfig.platformsKey}" entries must be '
189+
'lowercase snake_case identifiers starting with a letter (e.g. "custom_os"), '
190+
'got: "$invalidPlatform".',
191+
),
192+
),
132193
);
133194
}
134195
expect(

0 commit comments

Comments
 (0)