Show error on macOS if missing Local Network permissions (#161846)

loic-sharma · web-flow · commit 136d8e576a68 · 2025-01-23T18:50:22.000Z
### Background macOS Sequoia requires the user's permission to do multicast operations, which the Flutter tool does to connect to the Dart VM. If the app does not have permission to communicate with devices on the local network, the following happens: 1. Flutter tool starts a [multicast lookup](https://github.com/flutter/flutter/blob/bb2d34126cc8161dbe4a1bf23c925e48b732f670/packages/flutter_tools/lib/src/mdns_discovery.dart#L238-L241) 2. The mDNS client [sends data on the socket](https://github.com/flutter/packages/blob/973e8b59e24ba80d3c36a2bcfa914fcfd5e19943/packages/multicast_dns/lib/multicast_dns.dart#L219) 4. macOS blocks the operation. Dart's native socket implementation throws an `OSError` 5. Dart's `Socket.send` [catches the `OSError`](https://github.com/dart-lang/sdk/blob/da6dc03a15822d83d9180bd766c02d11aacdc06b/sdk/lib/_internal/vm/bin/socket_patch.dart#L1511-L1515), wraps it in a `SocketException`, and [schedules a microtask](https://github.com/dart-lang/sdk/blob/da6dc03a15822d83d9180bd766c02d11aacdc06b/sdk/lib/_internal/vm/bin/socket_patch.dart#L1513) that [reports the exception through the socket's stream](https://github.com/dart-lang/sdk/blob/95f00522676dff03f64fc715cb1835ad451faa4c/sdk/lib/_internal/vm/bin/socket_patch.dart#L3011) ([`Socket` is a `Stream`](https://api.dart.dev/dart-io/Socket-class.html)) 6. The mDNS client [does not listen to the socket stream's errors](https://github.com/flutter/packages/blob/973e8b59e24ba80d3c36a2bcfa914fcfd5e19943/packages/multicast_dns/lib/multicast_dns.dart#L155), so [the error is sent to the current `Zone`'s uncaught error handler](https://github.com/dart-lang/sdk/blob/95f00522676dff03f64fc715cb1835ad451faa4c/sdk/lib/async/stream_impl.dart#L553). ### Reproduction To reproduce this error on macOS... 1. Open System Settings > Privacy & Security > Local Network and toggle off Visual Studio Code 2. Run a Flutter app using a physical device ### Fix Ideally, we'd make `MDnsClient.lookup` throw an exception for this scenario. Unfortunately, the `MDnsClient` can have multiple lookup operations in parallel, and the `SocketException` doesn't give us enough information to match it back to a pending `MDnsClient` request. See flutter#8450 as an attempt to solve this in the `MDnsClient` layer. Instead, this fix introduces a `Zone` in the tool to catch the socket's uncaught exception. Follow-up to flutter/flutter#157638 See: flutter/flutter#150131 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord].  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
diff --git a/packages/flutter_tools/lib/src/mdns_discovery.dart b/packages/flutter_tools/lib/src/mdns_discovery.dart
@@ -96,7 +96,7 @@ class MDnsVmServiceDiscovery {
     final List<MDnsVmServiceDiscoveryResult> results = await _pollingVmService(
       _preliminaryClient ?? MDnsClient(),
       applicationId: applicationId,
-      deviceVmservicePort: deviceVmservicePort,
+      deviceVmServicePort: deviceVmservicePort,
       ipv6: ipv6,
       useDeviceIPAsHost: useDeviceIPAsHost,
       timeout: const Duration(seconds: 5),
@@ -192,7 +192,7 @@ class MDnsVmServiceDiscovery {
     final List<MDnsVmServiceDiscoveryResult> results = await _pollingVmService(
       client,
       applicationId: applicationId,
-      deviceVmservicePort: deviceVmservicePort,
+      deviceVmServicePort: deviceVmservicePort,
       deviceName: deviceName,
       ipv6: ipv6,
       useDeviceIPAsHost: useDeviceIPAsHost,
@@ -208,7 +208,74 @@ class MDnsVmServiceDiscovery {
   Future<List<MDnsVmServiceDiscoveryResult>> _pollingVmService(
     MDnsClient client, {
     String? applicationId,
-    int? deviceVmservicePort,
+    int? deviceVmServicePort,
+    String? deviceName,
+    bool ipv6 = false,
+    bool useDeviceIPAsHost = false,
+    required Duration timeout,
+    bool quitOnFind = false,
+  }) async {
+    // macOS blocks mDNS unless the app has Local Network permissions.
+    // Since the mDNS client does not handle errors from the socket's stream,
+    // socket exceptions are routed to the current zone. Create an error zone to
+    // catch the socket exception.
+    // See: https://github.com/flutter/flutter/issues/150131
+    final Completer<List<MDnsVmServiceDiscoveryResult>> completer =
+        Completer<List<MDnsVmServiceDiscoveryResult>>();
+    unawaited(
+      runZonedGuarded(
+        () async {
+          final List<MDnsVmServiceDiscoveryResult> results = await _doPollingVmService(
+            client,
+            applicationId: applicationId,
+            deviceVmServicePort: deviceVmServicePort,
+            deviceName: deviceName,
+            ipv6: ipv6,
+            useDeviceIPAsHost: useDeviceIPAsHost,
+            timeout: timeout,
+            quitOnFind: quitOnFind,
+          );
+
+          if (!completer.isCompleted) {
+            completer.complete(results);
+          }
+        },
+        (Object error, StackTrace stackTrace) {
+          if (!completer.isCompleted) {
+            completer.completeError(error, stackTrace);
+          }
+        },
+      ),
+    );
+
+    try {
+      return await completer.future;
+    } on SocketException catch (e, stackTrace) {
+      if (!globals.platform.isMacOS) {
+        rethrow;
+      }
+
+      _logger.printTrace(stackTrace.toString());
+
+      throwToolExit(
+        'Flutter could not connect to the Dart VM service.\n'
+        '\n'
+        'Please ensure your IDE or terminal app has permission to access '
+        'devices on the local network. This allows Flutter to connect to '
+        'the Dart VM.\n'
+        '\n'
+        'You can grant this permission in System Settings > Privacy & '
+        'Security > Local Network.\n'
+        '\n'
+        '$e',
+      );
+    }
+  }
+
+  Future<List<MDnsVmServiceDiscoveryResult>> _doPollingVmService(
+    MDnsClient client, {
+    String? applicationId,
+    int? deviceVmServicePort,
     String? deviceName,
     bool ipv6 = false,
     bool useDeviceIPAsHost = false,
@@ -232,27 +299,10 @@ class MDnsVmServiceDiscovery {
       final Set<String> uniqueDomainNamesInResults = <String>{};
 
       // Listen for mDNS connections until timeout.
-      final Stream<PtrResourceRecord> ptrResourceStream;
-
-      try {
-        ptrResourceStream = client.lookup<PtrResourceRecord>(
-          ResourceRecordQuery.serverPointer(dartVmServiceName),
-          timeout: timeout,
-        );
-      } on SocketException catch (e, stacktrace) {
-        _logger.printError(e.message);
-        _logger.printTrace(stacktrace.toString());
-        if (globals.platform.isMacOS) {
-          throwToolExit(
-            'You might be having a permissions issue with your IDE. '
-            'Please try going to '
-            'System Settings -> Privacy & Security -> Local Network -> '
-            '[Find your IDE] -> Toggle ON, then restart your phone.',
-          );
-        } else {
-          rethrow;
-        }
-      }
+      final Stream<PtrResourceRecord> ptrResourceStream = client.lookup<PtrResourceRecord>(
+        ResourceRecordQuery.serverPointer(dartVmServiceName),
+        timeout: timeout,
+      );
 
       await for (final PtrResourceRecord ptr in ptrResourceStream) {
         uniqueDomainNames.add(ptr.domainName);
@@ -292,8 +342,8 @@ class MDnsVmServiceDiscovery {
           );
         }
 
-        // If deviceVmservicePort is set, only use records that match it
-        if (deviceVmservicePort != null && srvRecord.port != deviceVmservicePort) {
+        // If deviceVmServicePort is set, only use records that match it
+        if (deviceVmServicePort != null && srvRecord.port != deviceVmServicePort) {
           continue;
         }
 
@@ -355,8 +405,8 @@ class MDnsVmServiceDiscovery {
       // the applicationId were found but other results were found, throw an error.
       if (applicationId != null && quitOnFind && results.isEmpty && uniqueDomainNames.isNotEmpty) {
         String message = 'Did not find a Dart VM Service advertised for $applicationId';
-        if (deviceVmservicePort != null) {
-          message += ' on port $deviceVmservicePort';
+        if (deviceVmServicePort != null) {
+          message += ' on port $deviceVmServicePort';
         }
         throwToolExit('$message.');
       }
diff --git a/packages/flutter_tools/test/general.shard/mdns_discovery_test.dart b/packages/flutter_tools/test/general.shard/mdns_discovery_test.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
+
 import 'package:file/memory.dart';
 import 'package:flutter_tools/src/base/io.dart';
 import 'package:flutter_tools/src/base/logger.dart';
@@ -610,13 +612,16 @@ void main() {
         );
       });
 
+      // On macOS, the mDNS client's socket stream creates a SocketException if
+      // the app running the tool does not have Local Network permissions.
+      // See: https://github.com/flutter/flutter/issues/150131
       test(
-        'On macOS, throw tool exit with a helpful message when client throws a SocketException on lookup',
+        'On macOS, tool exits with a helpful message when mDNS lookup throws a SocketException',
         () async {
           final MDnsClient client = FakeMDnsClient(
             <PtrResourceRecord>[],
             <String, List<SrvResourceRecord>>{},
-            socketExceptionOnStart: true,
+            socketExceptionOnLookup: true,
           );
 
           final MDnsVmServiceDiscovery portDiscovery = MDnsVmServiceDiscovery(
@@ -627,13 +632,55 @@ void main() {
           );
 
           expect(
-            portDiscovery.firstMatchingVmService(client),
+            () async => portDiscovery.firstMatchingVmService(client),
             throwsToolExit(
               message:
-                  'You might be having a permissions issue with your IDE. '
-                  'Please try going to '
-                  'System Settings -> Privacy & Security -> Local Network -> '
-                  '[Find your IDE] -> Toggle ON, then restart your phone.',
+                  'Flutter could not connect to the Dart VM service.\n'
+                  '\n'
+                  'Please ensure your IDE or terminal app has permission to access '
+                  'devices on the local network. This allows Flutter to connect to '
+                  'the Dart VM.\n'
+                  '\n'
+                  'You can grant this permission in System Settings > Privacy & '
+                  'Security > Local Network.\n',
+            ),
+          );
+        },
+        // [intended] This tool exit message only works for macOS
+        skip: !globals.platform.isMacOS,
+      );
+
+      // On macOS, the mDNS client's socket stream creates a SocketException if
+      // the app running the tool does not have Local Network permissions.
+      // See: https://github.com/flutter/flutter/issues/150131
+      test(
+        'On macOS, tool exits with a helpful message when mDNS lookup throws an uncaught SocketException',
+        () async {
+          final MDnsClient client = FakeMDnsClient(
+            <PtrResourceRecord>[],
+            <String, List<SrvResourceRecord>>{},
+            uncaughtSocketExceptionOnLookup: true,
+          );
+
+          final MDnsVmServiceDiscovery portDiscovery = MDnsVmServiceDiscovery(
+            mdnsClient: client,
+            logger: BufferLogger.test(),
+            flutterUsage: TestUsage(),
+            analytics: const NoOpAnalytics(),
+          );
+
+          expect(
+            () async => portDiscovery.firstMatchingVmService(client),
+            throwsToolExit(
+              message:
+                  'Flutter could not connect to the Dart VM service.\n'
+                  '\n'
+                  'Please ensure your IDE or terminal app has permission to access '
+                  'devices on the local network. This allows Flutter to connect to '
+                  'the Dart VM.\n'
+                  '\n'
+                  'You can grant this permission in System Settings > Privacy & '
+                  'Security > Local Network.\n',
             ),
           );
         },
@@ -1155,15 +1202,17 @@ class FakeMDnsClient extends Fake implements MDnsClient {
     this.txtResponse = const <String, List<TxtResourceRecord>>{},
     this.ipResponse = const <String, List<IPAddressResourceRecord>>{},
     this.osErrorOnStart = false,
-    this.socketExceptionOnStart = false,
+    this.socketExceptionOnLookup = false,
+    this.uncaughtSocketExceptionOnLookup = false,
   });
 
   final List<PtrResourceRecord> ptrRecords;
   final Map<String, List<SrvResourceRecord>> srvResponse;
   final Map<String, List<TxtResourceRecord>> txtResponse;
   final Map<String, List<IPAddressResourceRecord>> ipResponse;
   final bool osErrorOnStart;
-  final bool socketExceptionOnStart;
+  final bool socketExceptionOnLookup;
+  final bool uncaughtSocketExceptionOnLookup;
 
   @override
   Future<void> start({
@@ -1182,9 +1231,17 @@ class FakeMDnsClient extends Fake implements MDnsClient {
     ResourceRecordQuery query, {
     Duration timeout = const Duration(seconds: 5),
   }) {
-    if (socketExceptionOnStart) {
+    if (socketExceptionOnLookup) {
       throw const SocketException('Socket Exception');
     }
+
+    if (uncaughtSocketExceptionOnLookup) {
+      Zone.current.handleUncaughtError(
+        const SocketException('Socket Exception'),
+        StackTrace.current,
+      );
+    }
+
     if (T == PtrResourceRecord &&
         query.fullyQualifiedName == MDnsVmServiceDiscovery.dartVmServiceName) {
       return Stream<PtrResourceRecord>.fromIterable(ptrRecords) as Stream<T>;
