Merge pull request #331 from Workiva/background_process_tool

CPLAT-10037: Add a tool to make managing background processes easier.

Author: rmconsole6-wk

doc/tool-composition.md

@@ -140,6 +140,24 @@ final config = {
 };
 ```
 
+### `BackgroundProcessTool`
+
+The `BackgroundProcessTool` can be used in conjunction with `CompoundTool` to
+wrap a tool with the starting and stopping of a background subprocess:
+
+```dart
+final testServer = BackgroundProcessTool(
+    'node', ['tool/server.js'],
+    delayAfterStart: Duration(seconds: 1));
+
+final config = {
+  'test': CompoundTool()
+    ..addTool(testServer.starter, alwaysRun: true)
+    ..addTool(TestTool())
+    ..addTool(testServer.stopper, alwaysRun: true),
+};
+```
+
 ### Mapping args to tools
 
 `CompoundTool.addTool()` supports an optional `argMapper` parameter that can be

lib/dart_dev.dart

@@ -6,7 +6,7 @@ export 'src/tools/compound_tool.dart'
     show ArgMapper, CompoundTool, CompoundToolMixin, takeAllArgs;
 export 'src/tools/format_tool.dart'
     show FormatMode, Formatter, FormatterInputs, FormatTool;
-export 'src/tools/process_tool.dart' show ProcessTool;
+export 'src/tools/process_tool.dart' show BackgroundProcessTool, ProcessTool;
 export 'src/tools/test_tool.dart' show TestTool;
 export 'src/tools/tuneup_check_tool.dart' show TuneupCheckTool;
 export 'src/tools/webdev_serve_tool.dart' show WebdevServeTool;

lib/src/tools/process_tool.dart

@@ -1,13 +1,16 @@
 import 'dart:async';
 import 'dart:io';
 
-import 'package:dart_dev/src/utils/start_process_and_ensure_exit.dart';
+import 'package:io/io.dart';
 import 'package:logging/logging.dart';
+import 'package:pedantic/pedantic.dart';
 
 import '../dart_dev_tool.dart';
 import '../utils/assert_no_positional_args_nor_args_after_separator.dart';
+import '../utils/ensure_process_exit.dart';
 import '../utils/logging.dart';
 import '../utils/process_declaration.dart';
+import '../utils/start_process_and_ensure_exit.dart';
 
 final _log = Logger('Process');
 
@@ -56,3 +59,72 @@ class ProcessTool extends DevTool {
     return _process.exitCode;
   }
 }
+
+class BackgroundProcessTool {
+  final List<String> _args;
+  final String _executable;
+  final ProcessStartMode _mode;
+  final Duration _delayAfterStart;
+  final String _workingDirectory;
+
+  BackgroundProcessTool(String executable, List<String> args,
+      {ProcessStartMode mode,
+      Duration delayAfterStart,
+      String workingDirectory})
+      : _args = args,
+        _executable = executable,
+        _mode = mode,
+        _delayAfterStart = delayAfterStart,
+        _workingDirectory = workingDirectory;
+
+  Process get process => _process;
+  Process _process;
+
+  DevTool get starter => DevTool.fromFunction(_start);
+
+  DevTool get stopper => DevTool.fromFunction(_stop);
+
+  bool _processHasExited = false;
+
+  Future<int> _start(DevToolExecutionContext context) async {
+    if (context.argResults != null) {
+      assertNoPositionalArgsNorArgsAfterSeparator(
+          context.argResults, context.usageException,
+          commandName: context.commandName);
+    }
+    logSubprocessHeader(_log, '$_executable ${_args.join(' ')}');
+
+    final mode = _mode ??
+        (context.verbose
+            ? ProcessStartMode.inheritStdio
+            : ProcessStartMode.normal);
+    _process = await Process.start(_executable, _args,
+        mode: mode, workingDirectory: _workingDirectory);
+    ensureProcessExit(_process);
+    unawaited(_process.exitCode.then((_) => _processHasExited = true));
+
+    if (_delayAfterStart != null) {
+      await Future<void>.delayed(_delayAfterStart);
+    }
+
+    if (_processHasExited) {
+      // If the background process exits immediately or before the start delay,
+      // something is probably wrong, so return that exit code.
+      return _process.exitCode;
+    }
+
+    return ExitCode.success.code;
+  }
+
+  Future<int> _stop(DevToolExecutionContext context) async {
+    if (context.argResults != null) {
+      assertNoPositionalArgsNorArgsAfterSeparator(
+          context.argResults, context.usageException,
+          commandName: context.commandName);
+    }
+    _log.info('Stopping: $_executable ${_args.join(' ')}');
+    _process?.kill();
+    await _process.exitCode;
+    return ExitCode.success.code;
+  }
+}

lib/utils.dart

@@ -1,8 +1,9 @@
 export 'src/utils/assert_no_positional_args_nor_args_after_separator.dart';
 export 'src/utils/cached_pubspec.dart';
+export 'src/utils/ensure_process_exit.dart';
+export 'src/utils/global_package_is_active_and_compatible.dart';
 export 'src/utils/logging.dart'
     show humanReadable, logSubprocessHeader, logTimedAsync, logTimedSync;
-export 'src/utils/global_package_is_active_and_compatible.dart';
 export 'src/utils/package_is_immediate_dependency.dart';
 export 'src/utils/process_declaration.dart';
 export 'src/utils/run_process_and_ensure_exit.dart';

pubspec.yaml

@@ -15,6 +15,7 @@ dependencies:
   io: ^0.3.3
   logging: ^0.11.3+2
   path: ^1.6.2
+  pedantic: ^1.7.0
   pub_semver: ^1.4.2
   pubspec_parse: ^0.1.4
   stack_trace: ^1.9.3
@@ -23,7 +24,6 @@ dependencies:
 dev_dependencies:
   dependency_validator: ^1.3.0
   matcher: ^0.12.5
-  pedantic: ^1.7.0
   test: ^1.6.4
   test_descriptor: ^1.2.0
   test_process: ^1.0.4

test/functional.dart

@@ -55,6 +55,6 @@ Future<TestProcess> runDevToolFunctionalTest(
     }
   }
 
-  final args = <String>['run', 'dart_dev', ...command.split(' ')];
-  return TestProcess.start('pub', args, workingDirectory: d.sandbox);
+  final allArgs = <String>['run', 'dart_dev', command, ...?args];
+  return TestProcess.start('pub', allArgs, workingDirectory: d.sandbox);
 }

test/tools/process_tool_test.dart

@@ -5,6 +5,7 @@ import 'package:args/args.dart';
 import 'package:args/command_runner.dart';
 import 'package:dart_dev/dart_dev.dart';
 import 'package:logging/logging.dart';
+import 'package:pedantic/pedantic.dart';
 import 'package:test/test.dart';
 
 import '../log_matchers.dart';
@@ -42,4 +43,69 @@ void main() {
       DevTool.fromProcess('true', ['foo', 'bar']).run();
     });
   });
+
+  group('BackgroundProcessTool', () {
+    sharedDevToolTests(() => BackgroundProcessTool('true', []).starter);
+    sharedDevToolTests(() => BackgroundProcessTool('true', []).stopper);
+
+    test('starter runs the process without waiting for it to complete',
+        () async {
+      var processHasExited = false;
+      final tool = BackgroundProcessTool('sleep', ['5']);
+      expect(await tool.starter.run(), isZero);
+      unawaited(tool.process.exitCode.then((_) => processHasExited = true));
+      await Future<void>.delayed(Duration.zero);
+      expect(processHasExited, isFalse);
+      await tool.stopper.run();
+    });
+
+    test('stopper stops the process immediately', () async {
+      var processHasExited = false;
+      final tool = BackgroundProcessTool('sleep', ['5']);
+      final stopwatch = Stopwatch()..start();
+      expect(await tool.starter.run(), isZero);
+      unawaited(tool.process.exitCode.then((_) => processHasExited = true));
+      await Future<void>.delayed(Duration(seconds: 1));
+      expect(processHasExited, isFalse);
+      expect(await tool.stopper.run(), isZero);
+      expect(processHasExited, isTrue);
+      expect((stopwatch..stop()).elapsed.inSeconds, lessThan(3));
+    });
+
+    test('starter forwards the returned exit code', () async {
+      final tool = BackgroundProcessTool('false', [],
+          delayAfterStart: Duration(milliseconds: 500));
+      expect(await tool.starter.run(), isNonZero);
+    });
+
+    test('stopper always returns a zero exit code', () async {
+      final tool = BackgroundProcessTool('false', []);
+      await tool.starter.run();
+      await Future<void>.delayed(Duration(milliseconds: 500));
+      expect(await tool.stopper.run(), isZero);
+    });
+
+    test('can run from a custom working directory', () async {
+      final tool = BackgroundProcessTool('pwd', [],
+          workingDirectory: 'lib', delayAfterStart: Duration(seconds: 1));
+      expect(await tool.starter.run(), isZero);
+      final stdout =
+          (await tool.process.stdout.transform(utf8.decoder).join('')).trim();
+      expect(stdout, endsWith('/dart_dev/lib'));
+    });
+
+    test('throws UsageException when args are present', () {
+      final tool = BackgroundProcessTool('true', []);
+      expect(
+          () => tool.starter.run(
+              DevToolExecutionContext(argResults: ArgParser().parse(['foo']))),
+          throwsA(isA<UsageException>()));
+    });
+
+    test('logs the subprocess', () {
+      expect(Logger.root.onRecord,
+          emitsThrough(infoLogOf(contains('true foo bar'))));
+      BackgroundProcessTool('true', ['foo', 'bar']).starter.run();
+    });
+  });
 }