fuchsia_remote_connection.dart 24.5 KB
Newer Older
1
// Copyright 2018 The Chromium 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 37 38 39
  String address,
  int remotePort, [
  String interface,
  String configFile,
]);
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 84 85 86 87 88 89 90 91 92 93 94 95 96 97
/// 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),
/// and contains the service port of the VM as well as a URI to connect to it.
class DartVmEvent {
  DartVmEvent._({this.eventType, this.servicePort, this.uri});

  /// The URI used to connect to the Dart VM.
  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._useIpV6Loopback, this._sshCommandRunner)
107
    : _pollDartVms = false;
108 109

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

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 124 125

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

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

  /// Same as [FuchsiaRemoteConnection.connect] albeit with a provided
  /// [SshCommandRunner] instance.
134
  static Future<FuchsiaRemoteConnection> connectWithSshCommandRunner(SshCommandRunner commandRunner) async {
135
    final FuchsiaRemoteConnection connection = FuchsiaRemoteConnection._(
136 137
        isIpV6Address(commandRunner.address), commandRunner);
    await connection._forwardLocalPortsToDeviceServicePorts();
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 191
  ///
  /// 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([
    String address,
192 193 194
    String interface = '',
    String sshConfigPath,
  ]) async {
195 196 197
    address ??= Platform.environment['FUCHSIA_DEVICE_URL'];
    sshConfigPath ??= Platform.environment['FUCHSIA_SSH_CONFIG'];
    if (address == null) {
198
      throw FuchsiaRemoteConnectionError(
199 200 201 202 203 204 205 206 207 208
          'No address supplied, and \$FUCHSIA_DEVICE_URL not found.');
    }
    const String interfaceDelimiter = '%';
    if (address.contains(interfaceDelimiter)) {
      final List<String> addressAndInterface =
          address.split(interfaceDelimiter);
      address = addressAndInterface[0];
      interface = addressAndInterface[1];
    }

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

  /// 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 (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 228
      final DartVm vmService = _dartVmCache[pf.port];
      _dartVmCache[pf.port] = null;
229
      await vmService?.stop();
230
      await pf.stop();
231
    }
232 233 234 235 236 237
    for (PortForwarder pf in _dartVmPortMap.values) {
      final DartVm vmService = _dartVmCache[pf.port];
      _dartVmCache[pf.port] = null;
      await vmService?.stop();
      await pf.stop();
    }
238 239
    _dartVmCache.clear();
    _forwardedVmServicePorts.clear();
240 241 242 243
    _dartVmPortMap.clear();
    _pollDartVms = false;
  }

244 245 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([
    Pattern pattern,
    Duration timeout = _kIsolateFindTimeout,
253
    Duration vmConnectionTimeout = _kDartVmConnectionTimeout,
254
  ]) async {
255
    final Completer<List<IsolateRef>> completer = Completer<List<IsolateRef>>();
256 257 258 259 260
    _onDartVmEvent.listen(
      (DartVmEvent event) async {
        if (event.eventType == DartVmEventType.started) {
          _log.fine('New VM found on port: ${event.servicePort}. Searching '
              'for Isolate: $pattern');
261 262
          final DartVm vmService = await _getDartVm(event.uri.port,
              timeout: _kDartVmConnectionTimeout);
263
          // If the VM service is null, set the result to the empty list.
264
          final List<IsolateRef> result = await vmService
265 266
                  ?.getMainIsolatesByPattern(pattern, timeout: timeout) ??
              <IsolateRef>[];
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
          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);
  }

287 288
  /// Returns all Isolates running `main()` as matched by the [Pattern].
  ///
289 290 291
  /// 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`.
292
  Future<List<IsolateRef>> getMainIsolatesByPattern(
293
    Pattern pattern, {
294
    Duration timeout = _kIsolateFindTimeout,
295 296
    Duration vmConnectionTimeout = _kDartVmConnectionTimeout,
  }) async {
297 298
    // If for some reason there are no Dart VM's that are alive, wait for one to
    // start with the Isolate in question.
299
    if (_dartVmPortMap.isEmpty) {
300
      _log.fine('No live Dart VMs found. Awaiting new VM startup');
301 302
      return _waitForMainIsolatesByPattern(
          pattern, timeout, vmConnectionTimeout);
303 304 305 306 307 308
    }
    // 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>>>[];
    for (PortForwarder fp in _dartVmPortMap.values) {
309 310
      final DartVm vmService =
          await _getDartVm(fp.port, timeout: vmConnectionTimeout);
311 312 313
      if (vmService == null) {
        continue;
      }
314
      isolates.add(vmService.getMainIsolatesByPattern(pattern));
315
    }
316
    final List<IsolateRef> result =
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
      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;
            },
          );
        });
332 333 334 335 336 337 338 339 340 341 342

    // 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');
343 344
      return _waitForMainIsolatesByPattern(
          pattern, timeout, vmConnectionTimeout);
345
    }
346
    return result;
347 348 349 350
  }

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

  // 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>(
375 376 377
    Future<E> vmFunction(DartVm vmService), [
    bool queueEvents = true,
  ]) async {
378
    final List<E> result = <E>[];
379 380

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

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

405 406 407 408 409 410 411 412 413 414 415 416
  Uri _getDartVmUri(int port) {
    // While the IPv4 loopback can be used for the initial port forwarding
    // (see [PortForwarder.start]), the address is actually bound to the IPv6
    // loopback device, so connecting to the IPv4 loopback would fail when the
    // target address is IPv6 link-local.
    final String addr = _useIpV6Loopback
        ? 'http://\[$_ipv6Loopback\]:$port'
        : 'http://$_ipv4Loopback:$port';
    final Uri uri = Uri.parse(addr);
    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 422 423 424
  Future<DartVm> _getDartVm(
    int port, {
    Duration timeout = _kDartVmConnectionTimeout,
  }) async {
425
    if (!_dartVmCache.containsKey(port)) {
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(_getDartVmUri(port), timeout: timeout);
432 433 434 435 436 437 438 439
        _dartVmCache[port] = dartVm;
      } 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;
      }
440 441 442 443
    }
    return _dartVmCache[port];
  }

444 445 446 447
  /// 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).
448
  Future<void> _pollVms() async {
449 450 451 452 453 454 455 456 457 458 459
    await _checkPorts();
    final List<int> servicePorts = await getDeviceServicePorts();
    for (int servicePort in servicePorts) {
      if (!_stalePorts.contains(servicePort) &&
          !_dartVmPortMap.containsKey(servicePort)) {
        _dartVmPortMap[servicePort] = await fuchsiaPortForwardingFunction(
            _sshCommandRunner.address,
            servicePort,
            _sshCommandRunner.interface,
            _sshCommandRunner.sshConfigPath);

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

  /// Runs a dummy heartbeat command on all Dart VM instances.
  ///
  /// Removes any failing ports from the cache.
472
  Future<void> _checkPorts([ bool queueEvents = true ]) async {
473 474 475 476 477
    // Filters out stale ports after connecting. Ignores results.
    await _invokeForAllVms<Map<String, dynamic>>(
      (DartVm vmService) async {
        final Map<String, dynamic> res =
            await vmService.invokeRpc('getVersion');
478
        _log.fine('DartVM(${vmService.uri}) version check result: $res');
479 480 481 482 483 484
        return res;
      },
      queueEvents,
    );
  }

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

502 503 504 505 506 507 508 509 510
    for (PortForwarder pf in forwardedVmServicePorts) {
      // TODO(awdavies): Handle duplicates.
      _dartVmPortMap[pf.remotePort] = pf;
    }

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

    _pollDartVms = true;
511 512 513 514 515 516 517 518 519 520
  }

  /// 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 {
521
    final List<String> portPaths = await _sshCommandRunner
522
        .run('/bin/find /hub -name vmservice-port');
523
    final List<int> ports = <int>[];
524 525 526 527
    for (String path in portPaths) {
      if (path == '') {
        continue;
      }
528
      final List<String> lsOutput =
529
          await _sshCommandRunner.run('/bin/ls $path');
530 531 532 533 534 535 536
      for (String line in lsOutput) {
        if (line == '') {
          continue;
        }
        final int port = int.tryParse(line);
        if (port != null) {
          ports.add(port);
537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557
        }
      }
    }
    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 {
  /// Determines the port which is being forwarded from the local machine.
  int get port;

  /// 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 577 578 579 580 581 582 583 584 585 586 587 588
}

/// 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;
  final String _sshConfigPath;
  final String _interface;
  final bool _ipV6;

  @override
  int get port => _localSocket.port;

  @override
  int get remotePort => _remotePort;

  /// Starts SSH forwarding through a subprocess, and returns an instance of
  /// [_SshPortForwarder].
589 590 591 592 593 594
  static Future<_SshPortForwarder> start(
    String address,
    int remotePort, [
    String interface,
    String sshConfigPath,
  ]) async {
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617
    final bool isIpV6 = isIpV6Address(address);
    final ServerSocket localSocket = await _createLocalSocket();
    if (localSocket == null || localSocket.port == 0) {
      _log.warning('_SshPortForwarder failed to find a local port for '
          '$address:$remotePort');
      return null;
    }
    // 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
    // loopback (::1). While this can be used for forwarding to the destination
    // IPv6 interface, it cannot be used to connect to a websocket.
    final String formattedForwardingUrl =
        '${localSocket.port}:$_ipv4Loopback:$remotePort';
    final List<String> command = <String>['ssh'];
    if (isIpV6) {
      command.add('-6');
    }
    if (sshConfigPath != null) {
      command.addAll(<String>['-F', sshConfigPath]);
    }
    final String targetAddress =
        isIpV6 && interface.isNotEmpty ? '$address%$interface' : address;
618
    const String dummyRemoteCommand = 'true';
619 620
    command.addAll(<String>[
      '-nNT',
621
      '-f',
622 623 624
      '-L',
      formattedForwardingUrl,
      targetAddress,
625
      dummyRemoteCommand,
626 627
    ]);
    _log.fine("_SshPortForwarder running '${command.join(' ')}'");
628 629 630 631 632 633 634 635 636
    // 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) {
      return null;
    }
637
    final _SshPortForwarder result = _SshPortForwarder._(
638
        address, remotePort, localSocket, interface, sshConfigPath, isIpV6);
639 640 641
    _log.fine('Set up forwarding from ${localSocket.port} '
        'to $address port $remotePort');
    return result;
642 643 644 645 646
  }

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

  /// Attempts to find an available port.
  ///
  /// If successful returns a valid [ServerSocket] (which must be disconnected
  /// later).
  static Future<ServerSocket> _createLocalSocket() async {
    ServerSocket s;
    try {
      s = await ServerSocket.bind(_ipv4Loopback, 0);
    } catch (e) {
      // Failures are signaled by a return value of 0 from this function.
      _log.warning('_createLocalSocket failed: $e');
      return null;
    }
    return s;
  }
}