io.dart 5.07 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

/// This file serves as the single point of entry into the `dart:io` APIs
/// within Flutter tools.
///
/// In order to make Flutter tools more testable, we use the `FileSystem` APIs
/// in `package:file` rather than using the `dart:io` file APIs directly (see
/// `file_system.dart`). Doing so allows us to swap out local file system
/// access with mockable (or in-memory) file systems, making our tests hermetic
/// vis-a-vis file system access.
///
14 15 16
/// We also use `package:platform` to provide an abstraction away from the
/// static methods in the `dart:io` `Platform` class (see `platform.dart`). As
/// such, do not export Platform from this file!
17
///
18 19 20 21 22 23 24 25 26 27
/// To ensure that all file system and platform API access within Flutter tools
/// goes through the proper APIs, we forbid direct imports of `dart:io` (via a
/// test), forcing all callers to instead import this file, which exports the
/// blessed subset of `dart:io` that is legal to use in Flutter tools.
///
/// Because of the nature of this file, it is important that **platform and file
/// APIs not be exported from `dart:io` in this file**! Moreover, be careful
/// about any additional exports that you add to this file, as doing so will
/// increase the API surface that we have to test in Flutter tools, and the APIs
/// in `dart:io` can sometimes be hard to use in tests.
28 29
import 'dart:async';
import 'dart:io' as io show exit, ProcessSignal;
30 31 32

import 'package:meta/meta.dart';

33
import 'platform.dart';
34 35
import 'process.dart';

36 37 38
export 'dart:io'
    show
        BytesBuilder,
39
        // Directory         NO! Use `file_system.dart`
40
        exitCode,
41 42
        // File              NO! Use `file_system.dart`
        // FileSystemEntity  NO! Use `file_system.dart`
43 44 45 46 47 48 49 50 51 52 53
        GZIP,
        InternetAddress,
        IOException,
        IOSink,
        HttpClient,
        HttpClientRequest,
        HttpClientResponse,
        HttpHeaders,
        HttpRequest,
        HttpServer,
        HttpStatus,
54
        // Link              NO! Use `file_system.dart`
55
        pid,
56
        // Platform          NO! use `platform.dart`
57 58 59
        Process,
        ProcessException,
        ProcessResult,
60
        // ProcessSignal     NO! Use [ProcessSignal] below.
61
        ProcessStartMode,
62
        // RandomAccessFile  NO! Use `file_system.dart`
63 64 65
        ServerSocket,
        stderr,
        stdin,
66
        StdinException,
67 68 69 70 71 72 73 74 75 76
        stdout,
        Socket,
        SocketException,
        SYSTEM_ENCODING,
        WebSocket,
        WebSocketTransformer;

/// Exits the process with the given [exitCode].
typedef void ExitFunction(int exitCode);

77
final ExitFunction _defaultExitFunction = io.exit;
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94

ExitFunction _exitFunction = _defaultExitFunction;

/// Exits the process.
///
/// This is analogous to the `exit` function in `dart:io`, except that this
/// function may be set to a testing-friendly value by calling
/// [setExitFunctionForTests] (and then restored to its default implementation
/// with [restoreExitFunction]). The default implementation delegates to
/// `dart:io`.
ExitFunction get exit => _exitFunction;

/// Sets the [exit] function to a function that throws an exception rather
/// than exiting the process; this is intended for testing purposes.
@visibleForTesting
void setExitFunctionForTests([ExitFunction exitFunction]) {
  _exitFunction = exitFunction ?? (int exitCode) {
95
    throw new ProcessExit(exitCode, immediate: true);
96 97 98 99 100 101 102 103
  };
}

/// Restores the [exit] function to the `dart:io` implementation.
@visibleForTesting
void restoreExitFunction() {
  _exitFunction = _defaultExitFunction;
}
104 105 106 107 108 109 110 111 112 113 114 115 116 117

/// A portable version of [io.ProcessSignal].
///
/// Listening on signals that don't exist on the current platform is just a
/// no-op. This is in contrast to [io.ProcessSignal], where listening to
/// non-existent signals throws an exception.
class ProcessSignal implements io.ProcessSignal {
  @visibleForTesting
  const ProcessSignal(this._delegate);

  static const ProcessSignal SIGWINCH = const _PosixProcessSignal._(io.ProcessSignal.SIGWINCH);
  static const ProcessSignal SIGTERM = const _PosixProcessSignal._(io.ProcessSignal.SIGTERM);
  static const ProcessSignal SIGUSR1 = const _PosixProcessSignal._(io.ProcessSignal.SIGUSR1);
  static const ProcessSignal SIGUSR2 = const _PosixProcessSignal._(io.ProcessSignal.SIGUSR2);
118
  static const ProcessSignal SIGINT =  const ProcessSignal(io.ProcessSignal.SIGINT);
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

  final io.ProcessSignal _delegate;

  @override
  Stream<ProcessSignal> watch() {
    return _delegate.watch().map((io.ProcessSignal signal) => this);
  }

  @override
  String toString() => _delegate.toString();
}

/// A [ProcessSignal] that is only available on Posix platforms.
///
/// Listening to a [_PosixProcessSignal] is a no-op on Windows.
class _PosixProcessSignal extends ProcessSignal {

  const _PosixProcessSignal._(io.ProcessSignal wrappedSignal) : super(wrappedSignal);

  @override
  Stream<ProcessSignal> watch() {
    if (platform.isWindows)
      return new Stream<ProcessSignal>.empty();
    return super.watch();
  }
}