fuchsia_remote_connection.dart 24.5 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6 7 8 9 10 11 12 13 14
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:async';
import 'dart:io';

import 'package:process/process.dart';

import 'common/logging.dart';
import 'common/network.dart';
import 'dart/dart_vm.dart';
import 'runners/ssh_command_runner.dart';

15
final String _ipv4Loopback = InternetAddress.loopbackIPv4.address;
16

17
final String _ipv6Loopback = InternetAddress.loopbackIPv6.address;
18

19
const ProcessManager _processManager = LocalProcessManager();
20

21
const Duration _kIsolateFindTimeout = Duration(minutes: 1);
22

23 24
const Duration _kDartVmConnectionTimeout = Duration(seconds: 9);

25
const Duration _kVmPollInterval = Duration(milliseconds: 1500);
26

27
final Logger _log = Logger('FuchsiaRemoteConnection');
28 29 30 31 32 33

/// A function for forwarding ports on the local machine to a remote device.
///
/// Takes a remote `address`, the target device's port, and an optional
/// `interface` and `configFile`. The config file is used primarily for the
/// default SSH port forwarding configuration.
34
typedef PortForwardingFunction = Future<PortForwarder> Function(
35 36
  String address,
  int remotePort, [
37 38
  String? interface,
  String? configFile,
39
]);
40 41 42 43 44 45 46 47 48 49 50 51 52 53

/// The function for forwarding the local machine's ports to a remote Fuchsia
/// device.
///
/// Can be overwritten in the event that a different method is required.
/// Defaults to using SSH port forwarding.
PortForwardingFunction fuchsiaPortForwardingFunction = _SshPortForwarder.start;

/// Sets [fuchsiaPortForwardingFunction] back to the default SSH port forwarding
/// implementation.
void restoreFuchsiaPortForwardingFunction() {
  fuchsiaPortForwardingFunction = _SshPortForwarder.start;
}

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
/// A general error raised when something fails within a
/// [FuchsiaRemoteConnection].
class FuchsiaRemoteConnectionError extends Error {
  /// Basic constructor outlining the reason for the failure in `message`.
  FuchsiaRemoteConnectionError(this.message);

  /// The reason for the failure.
  final String message;

  @override
  String toString() {
    return '$FuchsiaRemoteConnectionError: $message';
  }
}

69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
/// An enum specifying a Dart VM's state.
enum DartVmEventType {
  /// The Dart VM has started.
  started,

  /// The Dart VM has stopped.
  ///
  /// This can mean either the host machine cannot be connect to, the VM service
  /// has shut down cleanly, or the VM service has crashed.
  stopped,
}

/// An event regarding the Dart VM.
///
/// Specifies the type of the event (whether the VM has started or has stopped),
84
/// and contains the service port of the VM as well as a URL to connect to it.
85
class DartVmEvent {
86
  DartVmEvent._({required this.eventType, required this.servicePort, required this.uri});
87

88
  /// The URL used to connect to the Dart VM.
89 90 91 92 93 94 95 96 97
  final Uri uri;

  /// The type of event regarding this instance of the Dart VM.
  final DartVmEventType eventType;

  /// The port on the host machine that the Dart VM service is/was running on.
  final int servicePort;
}

98 99 100 101 102
/// Manages a remote connection to a Fuchsia Device.
///
/// Provides affordances to observe and connect to Flutter views, isolates, and
/// perform actions on the Fuchsia device's various VM services.
///
Ian Hickson's avatar
Ian Hickson committed
103 104
/// This class can be connected to several instances of the Fuchsia device's
/// Dart VM at any given time.
105
class FuchsiaRemoteConnection {
106
  FuchsiaRemoteConnection._(this._useIpV6, this._sshCommandRunner)
107
    : _pollDartVms = false;
108 109

  bool _pollDartVms;
110 111
  final List<PortForwarder> _forwardedVmServicePorts = <PortForwarder>[];
  final SshCommandRunner _sshCommandRunner;
112
  final bool _useIpV6;
113

114 115 116 117 118 119
  /// A mapping of Dart VM ports (as seen on the target machine), to
  /// [PortForwarder] instances mapping from the local machine to the target
  /// machine.
  final Map<int, PortForwarder> _dartVmPortMap = <int, PortForwarder>{};

  /// Tracks stale ports so as not to reconnect while polling.
120
  final Set<int> _stalePorts = <int>{};
121 122 123

  /// A broadcast stream that emits events relating to Dart VM's as they update.
  Stream<DartVmEvent> get onDartVmEvent => _onDartVmEvent;
124
  late Stream<DartVmEvent> _onDartVmEvent;
125
  final StreamController<DartVmEvent> _dartVmEventController =
126
      StreamController<DartVmEvent>();
127

128
  /// VM service cache to avoid repeating handshakes across function
129
  /// calls. Keys a URI to a DartVm connection instance.
130
  final Map<Uri, DartVm?> _dartVmCache = <Uri, DartVm?>{};
131 132 133

  /// Same as [FuchsiaRemoteConnection.connect] albeit with a provided
  /// [SshCommandRunner] instance.
134
  static Future<FuchsiaRemoteConnection> connectWithSshCommandRunner(SshCommandRunner commandRunner) async {
135
    final FuchsiaRemoteConnection connection = FuchsiaRemoteConnection._(
136
        isIpV6Address(commandRunner.address), commandRunner);
137
    await connection._forwardOpenPortsToDeviceServicePorts();
138 139

    Stream<DartVmEvent> dartVmStream() {
140
      Future<void> listen() async {
141 142
        while (connection._pollDartVms) {
          await connection._pollVms();
143
          await Future<void>.delayed(_kVmPollInterval);
144 145 146 147 148 149 150 151 152
        }
        connection._dartVmEventController.close();
      }

      connection._dartVmEventController.onListen = listen;
      return connection._dartVmEventController.stream.asBroadcastStream();
    }

    connection._onDartVmEvent = dartVmStream();
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
    return connection;
  }

  /// Opens a connection to a Fuchsia device.
  ///
  /// Accepts an `address` to a Fuchsia device, and optionally a `sshConfigPath`
  /// in order to open the associated ssh_config for port forwarding.
  ///
  /// Will throw an [ArgumentError] if `address` is malformed.
  ///
  /// Once this function is called, the instance of [FuchsiaRemoteConnection]
  /// returned will keep all associated DartVM connections opened over the
  /// lifetime of the object.
  ///
  /// At its current state Dart VM connections will not be added or removed over
  /// the lifetime of this object.
  ///
  /// Throws an [ArgumentError] if the supplied `address` is not valid IPv6 or
  /// IPv4.
  ///
Ian Hickson's avatar
Ian Hickson committed
173 174 175 176
  /// If `address` is IPv6 link local (usually starts with `fe80::`), then
  /// `interface` will probably need to be set in order to connect successfully
  /// (that being the outgoing interface of your machine, not the interface on
  /// the target machine).
177 178 179 180 181 182 183 184 185 186 187 188 189 190
  ///
  /// Attempts to set `address` via the environment variable
  /// `FUCHSIA_DEVICE_URL` in the event that the argument is not passed.
  /// If `address` is not supplied, `interface` is also ignored, as the format
  /// is expected to contain the interface as well (in the event that it is
  /// link-local), like the following:
  ///
  /// ```
  /// fe80::1%eth0
  /// ```
  ///
  /// In the event that `FUCHSIA_SSH_CONFIG` is set in the environment, that
  /// will be used when `sshConfigPath` isn't supplied.
  static Future<FuchsiaRemoteConnection> connect([
191
    String? address,
192
    String interface = '',
193
    String? sshConfigPath,
194
  ]) async {
195 196 197
    address ??= Platform.environment['FUCHSIA_DEVICE_URL'];
    sshConfigPath ??= Platform.environment['FUCHSIA_SSH_CONFIG'];
    if (address == null) {
198
      throw FuchsiaRemoteConnectionError(
199
          r'No address supplied, and $FUCHSIA_DEVICE_URL not found.');
200 201 202 203 204 205 206 207 208
    }
    const String interfaceDelimiter = '%';
    if (address.contains(interfaceDelimiter)) {
      final List<String> addressAndInterface =
          address.split(interfaceDelimiter);
      address = addressAndInterface[0];
      interface = addressAndInterface[1];
    }

209
    return FuchsiaRemoteConnection.connectWithSshCommandRunner(
210
      SshCommandRunner(
211 212
        address: address,
        interface: interface,
213
        sshConfigPath: sshConfigPath,
214 215 216 217 218 219 220 221 222
      ),
    );
  }

  /// Closes all open connections.
  ///
  /// Any objects that this class returns (including any child objects from
  /// those objects) will subsequently have its connection closed as well, so
  /// behavior for them will be undefined.
223
  Future<void> stop() async {
224
    for (final PortForwarder pf in _forwardedVmServicePorts) {
225 226
      // Closes VM service first to ensure that the connection is closed cleanly
      // on the target before shutting down the forwarding itself.
227
      final Uri uri = _getDartVmUri(pf);
228
      final DartVm? vmService = _dartVmCache[uri];
229
      _dartVmCache[uri] = null;
230
      await vmService?.stop();
231
      await pf.stop();
232
    }
233
    for (final PortForwarder pf in _dartVmPortMap.values) {
234
      final Uri uri = _getDartVmUri(pf);
235
      final DartVm? vmService = _dartVmCache[uri];
236
      _dartVmCache[uri] = null;
237 238 239
      await vmService?.stop();
      await pf.stop();
    }
240 241
    _dartVmCache.clear();
    _forwardedVmServicePorts.clear();
242 243 244 245
    _dartVmPortMap.clear();
    _pollDartVms = false;
  }

246 247 248 249 250 251 252
  /// Helper method for [getMainIsolatesByPattern].
  ///
  /// Called when either there are no Isolates that exist that match
  /// `pattern`, or there are not yet any active Dart VM's on the system
  /// (possible when the Isolate we're attempting to connect to is in the only
  /// instance of the Dart VM and its service port has not yet opened).
  Future<List<IsolateRef>> _waitForMainIsolatesByPattern([
253
    Pattern? pattern,
254
    Duration timeout = _kIsolateFindTimeout,
255
    Duration vmConnectionTimeout = _kDartVmConnectionTimeout,
256
  ]) async {
257
    final Completer<List<IsolateRef>> completer = Completer<List<IsolateRef>>();
258 259 260 261 262
    _onDartVmEvent.listen(
      (DartVmEvent event) async {
        if (event.eventType == DartVmEventType.started) {
          _log.fine('New VM found on port: ${event.servicePort}. Searching '
              'for Isolate: $pattern');
263
          final DartVm? vmService = await _getDartVm(event.uri);
264
          // If the VM service is null, set the result to the empty list.
265
          final List<IsolateRef> result = await vmService?.getMainIsolatesByPattern(pattern!) ?? <IsolateRef>[];
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
          if (result.isNotEmpty) {
            if (!completer.isCompleted) {
              completer.complete(result);
            } else {
              _log.warning('Found more than one Dart VM containing Isolates '
                  'that match the pattern "$pattern".');
            }
          }
        }
      },
      onDone: () {
        if (!completer.isCompleted) {
          _log.warning('Terminating isolate search for "$pattern"'
              ' before timeout reached.');
        }
      },
    );
    return completer.future.timeout(timeout);
  }

286 287
  /// Returns all Isolates running `main()` as matched by the [Pattern].
  ///
288 289 290
  /// If there are no live Dart VM's or the Isolate cannot be found, waits until
  /// either `timeout` is reached, or a Dart VM starts up with a name that
  /// matches `pattern`.
291
  Future<List<IsolateRef>> getMainIsolatesByPattern(
292
    Pattern pattern, {
293
    Duration timeout = _kIsolateFindTimeout,
294 295
    Duration vmConnectionTimeout = _kDartVmConnectionTimeout,
  }) async {
296 297
    // If for some reason there are no Dart VM's that are alive, wait for one to
    // start with the Isolate in question.
298
    if (_dartVmPortMap.isEmpty) {
299
      _log.fine('No live Dart VMs found. Awaiting new VM startup');
300 301
      return _waitForMainIsolatesByPattern(
          pattern, timeout, vmConnectionTimeout);
302 303 304 305 306
    }
    // Accumulate a list of eventual IsolateRef lists so that they can be loaded
    // simultaneously via Future.wait.
    final List<Future<List<IsolateRef>>> isolates =
        <Future<List<IsolateRef>>>[];
307
    for (final PortForwarder fp in _dartVmPortMap.values) {
308
      final DartVm? vmService =
309
      await _getDartVm(_getDartVmUri(fp), timeout: vmConnectionTimeout);
310 311 312
      if (vmService == null) {
        continue;
      }
313
      isolates.add(vmService.getMainIsolatesByPattern(pattern));
314
    }
315
    final List<IsolateRef> result =
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
      await Future.wait<List<IsolateRef>>(isolates)
        .timeout(timeout)
        .then<List<IsolateRef>>((List<List<IsolateRef>> listOfLists) {
          final List<List<IsolateRef>> mutableListOfLists =
            List<List<IsolateRef>>.from(listOfLists)
              ..retainWhere((List<IsolateRef> list) => list.isNotEmpty);
          // Folds the list of lists into one flat list.
          return mutableListOfLists.fold<List<IsolateRef>>(
            <IsolateRef>[],
            (List<IsolateRef> accumulator, List<IsolateRef> element) {
              accumulator.addAll(element);
              return accumulator;
            },
          );
        });
331 332 333 334 335 336 337 338 339 340 341

    // If no VM instance anywhere has this, it's possible it hasn't spun up
    // anywhere.
    //
    // For the time being one Flutter Isolate runs at a time in each VM, so for
    // now this will wait until the timer runs out or a new Dart VM starts that
    // contains the Isolate in question.
    //
    // TODO(awdavies): Set this up to handle multiple Isolates per Dart VM.
    if (result.isEmpty) {
      _log.fine('No instance of the Isolate found. Awaiting new VM startup');
342 343
      return _waitForMainIsolatesByPattern(
          pattern, timeout, vmConnectionTimeout);
344
    }
345
    return result;
346 347 348 349
  }

  /// Returns a list of [FlutterView] objects.
  ///
350
  /// This is run across all connected Dart VM connections that this class is
351 352
  /// managing.
  Future<List<FlutterView>> getFlutterViews() async {
353
    if (_dartVmPortMap.isEmpty) {
354
      return <FlutterView>[];
355
    }
356 357
    final List<List<FlutterView>> flutterViewLists =
        await _invokeForAllVms<List<FlutterView>>((DartVm vmService) async {
358
      return vmService.getAllFlutterViews();
359 360 361 362 363 364
    });
    final List<FlutterView> results = flutterViewLists.fold<List<FlutterView>>(
        <FlutterView>[], (List<FlutterView> acc, List<FlutterView> element) {
      acc.addAll(element);
      return acc;
    });
365
    return List<FlutterView>.unmodifiable(results);
366 367 368 369 370 371 372 373
  }

  // Calls all Dart VM's, returning a list of results.
  //
  // A side effect of this function is that internally tracked port forwarding
  // will be updated in the event that ports are found to be broken/stale: they
  // will be shut down and removed from tracking.
  Future<List<E>> _invokeForAllVms<E>(
374
    Future<E> Function(DartVm vmService) vmFunction, [
375 376
    bool queueEvents = true,
  ]) async {
377
    final List<E> result = <E>[];
378 379

    // Helper function loop.
380
    Future<void> shutDownPortForwarder(PortForwarder pf) async {
381 382 383
      await pf.stop();
      _stalePorts.add(pf.remotePort);
      if (queueEvents) {
384
        _dartVmEventController.add(DartVmEvent._(
385 386
          eventType: DartVmEventType.stopped,
          servicePort: pf.remotePort,
387
          uri: _getDartVmUri(pf),
388 389 390 391
        ));
      }
    }

392
    for (final PortForwarder pf in _dartVmPortMap.values) {
393
      final DartVm? service = await _getDartVm(_getDartVmUri(pf));
394
      if (service == null) {
395
        await shutDownPortForwarder(pf);
396 397
      } else {
        result.add(await vmFunction(service));
398
      }
399
    }
400
    _stalePorts.forEach(_dartVmPortMap.remove);
401
    return result;
402 403
  }

404
  Uri _getDartVmUri(PortForwarder pf) {
405
    String? addr;
406 407 408
    if (pf.openPortAddress == null) {
      addr = _useIpV6 ? '[$_ipv6Loopback]' : _ipv4Loopback;
    } else {
409
      addr = isIpV6Address(pf.openPortAddress!)
410 411 412 413
        ? '[${pf.openPortAddress}]'
        : pf.openPortAddress;
    }
    final Uri uri = Uri.http('$addr:${pf.port}', '/');
414 415 416
    return uri;
  }

417 418 419 420
  /// Attempts to create a connection to a Dart VM.
  ///
  /// Returns null if either there is an [HttpException] or a
  /// [TimeoutException], else a [DartVm] instance.
421
  Future<DartVm?> _getDartVm(
422
    Uri uri, {
423 424
    Duration timeout = _kDartVmConnectionTimeout,
  }) async {
425
    if (!_dartVmCache.containsKey(uri)) {
426 427 428 429
      // When raising an HttpException this means that there is no instance of
      // the Dart VM to communicate with.  The TimeoutException is raised when
      // the Dart VM instance is shut down in the middle of communicating.
      try {
430 431
        final DartVm dartVm = await DartVm.connect(uri, timeout: timeout);
        _dartVmCache[uri] = dartVm;
432 433 434 435 436 437 438
      } on HttpException {
        _log.warning('HTTP Exception encountered connecting to new VM');
        return null;
      } on TimeoutException {
        _log.warning('TimeoutException encountered connecting to new VM');
        return null;
      }
439
    }
440
    return _dartVmCache[uri];
441 442
  }

443 444 445 446
  /// Checks for changes in the list of Dart VM instances.
  ///
  /// If there are new instances of the Dart VM, then connections will be
  /// attempted (after clearing out stale connections).
447
  Future<void> _pollVms() async {
448 449
    await _checkPorts();
    final List<int> servicePorts = await getDeviceServicePorts();
450
    for (final int servicePort in servicePorts) {
451 452 453 454 455 456 457 458
      if (!_stalePorts.contains(servicePort) &&
          !_dartVmPortMap.containsKey(servicePort)) {
        _dartVmPortMap[servicePort] = await fuchsiaPortForwardingFunction(
            _sshCommandRunner.address,
            servicePort,
            _sshCommandRunner.interface,
            _sshCommandRunner.sshConfigPath);

459
        _dartVmEventController.add(DartVmEvent._(
460 461
          eventType: DartVmEventType.started,
          servicePort: servicePort,
462
          uri: _getDartVmUri(_dartVmPortMap[servicePort]!),
463 464 465 466 467 468 469 470
        ));
      }
    }
  }

  /// Runs a dummy heartbeat command on all Dart VM instances.
  ///
  /// Removes any failing ports from the cache.
471
  Future<void> _checkPorts([ bool queueEvents = true ]) async {
472
    // Filters out stale ports after connecting. Ignores results.
473
    await _invokeForAllVms<void>(
474
      (DartVm vmService) async {
475
        await vmService.ping();
476 477 478 479 480
      },
      queueEvents,
    );
  }

481
  /// Forwards a series of open ports to the remote device.
482 483 484
  ///
  /// When this function is run, all existing forwarded ports and connections
  /// are reset by way of [stop].
485
  Future<void> _forwardOpenPortsToDeviceServicePorts() async {
486 487
    await stop();
    final List<int> servicePorts = await getDeviceServicePorts();
488 489 490
    final List<PortForwarder?> forwardedVmServicePorts =
      await Future.wait<PortForwarder?>(
        servicePorts.map<Future<PortForwarder?>>((int deviceServicePort) {
491 492 493 494 495 496
          return fuchsiaPortForwardingFunction(
              _sshCommandRunner.address,
              deviceServicePort,
              _sshCommandRunner.interface,
              _sshCommandRunner.sshConfigPath);
        }));
497

498
    for (final PortForwarder? pf in forwardedVmServicePorts) {
499
      // TODO(awdavies): Handle duplicates.
500
      _dartVmPortMap[pf!.remotePort] = pf;
501 502 503 504 505 506
    }

    // Don't queue events, since this is the initial forwarding.
    await _checkPorts(false);

    _pollDartVms = true;
507 508 509 510 511 512 513 514 515 516
  }

  /// Gets the open Dart VM service ports on a remote Fuchsia device.
  ///
  /// The method attempts to get service ports through an SSH connection. Upon
  /// successfully getting the VM service ports, returns them as a list of
  /// integers. If an empty list is returned, then no Dart VM instances could be
  /// found. An exception is thrown in the event of an actual error when
  /// attempting to acquire the ports.
  Future<List<int>> getDeviceServicePorts() async {
517
    final List<String> portPaths = await _sshCommandRunner
518
        .run('/bin/find /hub -name vmservice-port');
519
    final List<int> ports = <int>[];
520
    for (final String path in portPaths) {
521 522 523
      if (path == '') {
        continue;
      }
524
      final List<String> lsOutput =
525
          await _sshCommandRunner.run('/bin/ls $path');
526
      for (final String line in lsOutput) {
527 528 529
        if (line == '') {
          continue;
        }
530
        final int? port = int.tryParse(line);
531 532
        if (port != null) {
          ports.add(port);
533 534 535 536 537 538 539 540 541 542 543 544 545 546
        }
      }
    }
    return ports;
  }
}

/// Defines an interface for port forwarding.
///
/// When a port forwarder is initialized, it is intended to save a port through
/// which a connection is persisted along the lifetime of this object.
///
/// To shut down a port forwarder you must call the [stop] function.
abstract class PortForwarder {
547
  /// Determines the port which is being forwarded.
548 549
  int get port;

550 551
  /// The address on which the open port is accessible. Defaults to null to
  /// indicate local loopback.
552
  String? get openPortAddress => null;
553

554 555 556 557
  /// The destination port on the other end of the port forwarding tunnel.
  int get remotePort;

  /// Shuts down and cleans up port forwarding.
558
  Future<void> stop();
559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576
}

/// Instances of this class represent a running SSH tunnel.
///
/// The SSH tunnel is from the host to a VM service running on a Fuchsia device.
class _SshPortForwarder implements PortForwarder {
  _SshPortForwarder._(
    this._remoteAddress,
    this._remotePort,
    this._localSocket,
    this._interface,
    this._sshConfigPath,
    this._ipV6,
  );

  final String _remoteAddress;
  final int _remotePort;
  final ServerSocket _localSocket;
577 578
  final String? _sshConfigPath;
  final String? _interface;
579 580 581 582 583
  final bool _ipV6;

  @override
  int get port => _localSocket.port;

584 585 586
  @override
  String get openPortAddress => _ipV6 ? _ipv6Loopback : _ipv4Loopback;

587 588 589 590 591
  @override
  int get remotePort => _remotePort;

  /// Starts SSH forwarding through a subprocess, and returns an instance of
  /// [_SshPortForwarder].
592 593 594
  static Future<_SshPortForwarder> start(
    String address,
    int remotePort, [
595 596
    String? interface,
    String? sshConfigPath,
597
  ]) async {
598
    final bool isIpV6 = isIpV6Address(address);
599
    final ServerSocket? localSocket = await _createLocalSocket();
600 601 602
    if (localSocket == null || localSocket.port == 0) {
      _log.warning('_SshPortForwarder failed to find a local port for '
          '$address:$remotePort');
603
      throw StateError('Unable to create a socket or no available ports.');
604 605 606 607
    }
    // TODO(awdavies): The square-bracket enclosure for using the IPv6 loopback
    // didn't appear to work, but when assigning to the IPv4 loopback device,
    // netstat shows that the local port is actually being used on the IPv6
608 609 610
    // loopback (::1). Therefore, while the IPv4 loopback can be used for
    // forwarding to the destination IPv6 interface, when connecting to the
    // websocket, the IPV6 loopback should be used.
611 612 613
    final String formattedForwardingUrl =
        '${localSocket.port}:$_ipv4Loopback:$remotePort';
    final String targetAddress =
614
        isIpV6 && interface!.isNotEmpty ? '$address%$interface' : address;
615
    const String dummyRemoteCommand = 'true';
616 617 618 619 620
    final List<String> command = <String>[
      'ssh',
      if (isIpV6) '-6',
      if (sshConfigPath != null)
        ...<String>['-F', sshConfigPath],
621
      '-nNT',
622
      '-f',
623 624 625
      '-L',
      formattedForwardingUrl,
      targetAddress,
626
      dummyRemoteCommand,
627
    ];
628
    _log.fine("_SshPortForwarder running '${command.join(' ')}'");
629 630 631 632 633 634 635
    // Must await for the port forwarding function to completer here, as
    // forwarding must be completed before surfacing VM events (as the user may
    // want to connect immediately after an event is surfaced).
    final ProcessResult processResult = await _processManager.run(command);
    _log.fine("'${command.join(' ')}' exited with exit code "
        '${processResult.exitCode}');
    if (processResult.exitCode != 0) {
636
      throw StateError('Unable to start port forwarding');
637
    }
638
    final _SshPortForwarder result = _SshPortForwarder._(
639
        address, remotePort, localSocket, interface, sshConfigPath, isIpV6);
640 641 642
    _log.fine('Set up forwarding from ${localSocket.port} '
        'to $address port $remotePort');
    return result;
643 644 645 646 647
  }

  /// Kills the SSH forwarding command, then to ensure no ports are forwarded,
  /// runs the SSH 'cancel' command to shut down port forwarding completely.
  @override
648
  Future<void> stop() async {
649 650 651 652
    // Cancel the forwarding request. See [start] for commentary about why this
    // uses the IPv4 loopback.
    final String formattedForwardingUrl =
        '${_localSocket.port}:$_ipv4Loopback:$_remotePort';
653
    final String targetAddress = _ipV6 && _interface!.isNotEmpty
654 655
        ? '$_remoteAddress%$_interface'
        : _remoteAddress;
656 657
    final String? sshConfigPath = _sshConfigPath;
    final List<String> command = <String>[
658
      'ssh',
659 660
      if (sshConfigPath != null)
        ...<String>['-F', sshConfigPath],
661 662 663 664 665
      '-O',
      'cancel',
      '-L',
      formattedForwardingUrl,
      targetAddress,
666
    ];
667 668 669 670
    _log.fine(
        'Shutting down SSH forwarding with command: ${command.join(' ')}');
    final ProcessResult result = await _processManager.run(command);
    if (result.exitCode != 0) {
671 672
      _log.warning('Command failed:\nstdout: ${result.stdout}'
          '\nstderr: ${result.stderr}');
673 674 675 676 677 678 679 680
    }
    _localSocket.close();
  }

  /// Attempts to find an available port.
  ///
  /// If successful returns a valid [ServerSocket] (which must be disconnected
  /// later).
681
  static Future<ServerSocket?> _createLocalSocket() async {
682
    try {
683
      return await ServerSocket.bind(_ipv4Loopback, 0);
684
    } catch (e) {
685 686
      // We should not be catching all errors arbitrarily here, this might hide real errors.
      // TODO(ianh): Determine which exceptions to catch here.
687 688 689 690 691
      _log.warning('_createLocalSocket failed: $e');
      return null;
    }
  }
}