feat(dart_frog_cli): add devserver lifecycle (#730)

Author: renancaraujo

packages/dart_frog_cli/lib/src/commands/dev/dev.dart

@@ -70,13 +70,22 @@ class DevCommand extends DartFrogCommand {
         _defaultDartVmServicePort;
     final generator = await _generator(dartFrogDevServerBundle);
 
-    final result = await _devServerRunnerBuilder(
+    final devServer = _devServerRunnerBuilder(
       devServerBundleGenerator: generator,
       logger: logger,
       workingDirectory: cwd,
       port: port,
       dartVmServicePort: dartVmServicePort,
-    ).start();
+    );
+
+    try {
+      await devServer.start();
+    } on DartFrogDevServerException catch (e) {
+      logger.err(e.message);
+      return ExitCode.software.code;
+    }
+
+    final result = await devServer.exitCode;
 
     return result.code;
   }

packages/dart_frog_cli/lib/src/dev_server_runner/dev_server_runner.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io' as io;
 
@@ -39,9 +40,18 @@ final _dartVmServiceAlreadyInUseErrorRegex = RegExp(
   multiLine: true,
 );
 
-// TODO(renancaraujo): Add reload and stop methods.
 /// {@template dev_server_runner}
 /// A class that manages a local development server process lifecycle.
+///
+/// The [DevServerRunner] is responsible for:
+/// - Generating the dev server runtime code.
+/// - Starting the dev server process.
+/// - Watching for file changes.
+/// - Restarting the dev server process when files change.
+/// - Stopping the dev server process when requested or under external
+/// circumstances (server process killed or watcher stopped).
+///
+/// After stopped, a [DevServerRunner] instance cannot be restarted.
 /// {@endtemplate}
 class DevServerRunner {
   /// {@macro dev_server_runner}
@@ -58,9 +68,7 @@ class DevServerRunner {
     @visibleForTesting io.ProcessSignal? sigint,
     @visibleForTesting ProcessStart? startProcess,
     @visibleForTesting ProcessRun? runProcess,
-    @visibleForTesting Exit? exit,
   })  : _directoryWatcher = directoryWatcher ?? DirectoryWatcher.new,
-        _exit = exit ?? io.exit,
         _isWindows = isWindows ?? io.Platform.isWindows,
         _sigint = sigint ?? io.ProcessSignal.sigint,
         _startProcess = startProcess ?? io.Process.start,
@@ -92,16 +100,34 @@ class DevServerRunner {
   final ProcessStart _startProcess;
   final ProcessRun _runProcess;
   final RestorableDirectoryGeneratorTargetBuilder _generatorTarget;
-  final Exit _exit;
   final bool _isWindows;
-
   final io.ProcessSignal _sigint;
-  late final _target = _generatorTarget(
-    io.Directory(path.join(workingDirectory.path, '.dart_frog')),
-    logger: logger,
+
+  late final _generatedDirectory = io.Directory(
+    path.join(workingDirectory.path, '.dart_frog'),
   );
+  late final _target = _generatorTarget(_generatedDirectory, logger: logger);
 
   var _isReloading = false;
+  io.Process? _serverProcess;
+  StreamSubscription<WatchEvent>? _watcherSubscription;
+
+  /// Whether the dev server is running.
+  bool get isServerRunning => _serverProcess != null;
+
+  /// Whether the dev server is watching for file changes.
+  bool get isWatching => _watcherSubscription != null;
+
+  /// Whether the dev server has been started and stopped.
+  bool get isCompleted => _exitCodeCompleter.isCompleted;
+
+  final Completer<ExitCode> _exitCodeCompleter = Completer<ExitCode>();
+
+  /// A [Future] that completes when the dev server stops.
+  ///
+  /// The [Future] will complete with the [ExitCode] indicating the conditions
+  /// under which the dev server ended.
+  Future<ExitCode> get exitCode => _exitCodeCompleter.future;
 
   Future<void> _codegen() async {
     logger.detail('[codegen] running pre-gen...');
@@ -129,8 +155,15 @@ class DevServerRunner {
     logger.detail('[codegen] reload complete.');
   }
 
-  Future<void> _killProcess(io.Process process) async {
+  // Internal method to kill the server process.
+  // Make sure to call `stop` after calling this method to also stop the
+  // watcher.
+  Future<void> _killServerProcess() async {
     _isReloading = false;
+    final process = _serverProcess;
+    if (process == null) {
+      return;
+    }
     logger.detail('[process] killing process...');
     if (_isWindows) {
       logger.detail('[process] taskkill /F /T /PID ${process.pid}');
@@ -139,33 +172,73 @@ class DevServerRunner {
       logger.detail('[process] process.kill()...');
       process.kill();
     }
+    _serverProcess = null;
     logger.detail('[process] killing process complete.');
   }
 
-  // TODO(renancaraujo): this method returns a future that completes when the
-  // process is killed, but it should return a future that completes when the
-  // process is finished starting.
-  /// Starts the development server.
-  Future<ExitCode> start() async {
-    var isHotReloadingEnabled = false;
+  // Internal method to cancel the watcher subscription.
+  // Make sure to call `stop` after calling this method to also stop the
+  // server process.
+  Future<void> _cancelWatcherSubscription() async {
+    if (!isWatching) {
+      return;
+    }
+    logger.detail('[watcher] cancelling subscription...');
+    await _watcherSubscription!.cancel();
+    _watcherSubscription = null;
+    logger.detail('[watcher] cancelling subscription complete.');
+  }
+
+  /// Starts the development server and a [DirectoryWatcher] subscription
+  /// that will regenerate the dev server code when files change.
+  ///
+  /// This method will throw a [DartFrogDevServerException] if called while
+  /// the dev server has been started.
+  ///
+  /// This method will throw a [DartFrogDevServerException] if called after
+  /// [stop] has been called.
+  Future<void> start() async {
+    if (isCompleted) {
+      throw DartFrogDevServerException(
+        'Cannot start a dev server after it has been stopped.',
+      );
+    }
+
+    if (isServerRunning) {
+      throw DartFrogDevServerException(
+        'Cannot start a dev server while already running.',
+      );
+    }
 
     Future<void> serve() async {
+      var isHotReloadingEnabled = false;
       final enableVmServiceFlag = '--enable-vm-service=$dartVmServicePort';
 
+      final serverDartFilePath = path.join(
+        _generatedDirectory.absolute.path,
+        'server.dart',
+      );
+
       logger.detail(
-        '''[process] dart $enableVmServiceFlag ${path.join('.dart_frog', 'server.dart')}''',
+        '''[process] dart $enableVmServiceFlag $serverDartFilePath''',
       );
 
-      final process = await _startProcess(
+      final process = _serverProcess = await _startProcess(
         'dart',
-        [enableVmServiceFlag, path.join('.dart_frog', 'server.dart')],
+        [enableVmServiceFlag, serverDartFilePath],
         runInShell: true,
       );
 
       // On Windows listen for CTRL-C and use taskkill to kill
       // the spawned process along with any child processes.
       // https://github.com/dart-lang/sdk/issues/22470
-      if (_isWindows) _sigint.watch().listen((_) => _killProcess(process));
+      if (_isWindows) {
+        _sigint.watch().listen((_) {
+          // Do not await on sigint
+          _killServerProcess().ignore();
+          stop();
+        });
+      }
 
       var hasError = false;
       process.stderr.listen((_) async {
@@ -194,9 +267,11 @@ class DevServerRunner {
 
         if ((!isHotReloadingEnabled && !isSDKWarning) ||
             isDartVMServiceAlreadyInUseError) {
-          await _killProcess(process);
-          logger.detail('[process] exit(1)');
-          _exit(1);
+          await _killServerProcess();
+          const exitCode = ExitCode.software;
+          logger.detail('[process] exit(${exitCode.code})');
+          await stop(exitCode);
+          return;
         }
 
         await _target.rollback();
@@ -211,6 +286,15 @@ class DevServerRunner {
         if (shouldCacheSnapshot) _target.cacheLatestSnapshot();
         hasError = false;
       });
+
+      process.exitCode.then((code) async {
+        if (isCompleted) return;
+        logger
+          ..info('[process] Server process has been terminated')
+          ..detail('[process] exit($code)');
+        await _killServerProcess();
+        await stop(ExitCode.unavailable);
+      }).ignore();
     }
 
     final progress = logger.progress('Serving');
@@ -235,13 +319,59 @@ class DevServerRunner {
     }
 
     final watcher = _directoryWatcher(path.join(cwdPath));
-    final subscription = watcher.events
+    _watcherSubscription = watcher.events
         .where(shouldReload)
         .debounce(Duration.zero)
         .listen((_) => _reload());
 
-    await subscription.asFuture<void>();
-    await subscription.cancel();
-    return ExitCode.success;
+    _watcherSubscription!.asFuture<void>().then((_) async {
+      await _cancelWatcherSubscription();
+      await stop();
+    }).catchError((_) async {
+      await _cancelWatcherSubscription();
+      await stop(ExitCode.software);
+    }).ignore();
+  }
+
+  /// Stops the development server and the watcher then
+  /// completes [DevServerRunner.exitCode] with the given [exitCode].
+  ///
+  /// If [exitCode] is not provided, it defaults to [ExitCode.success].
+  ///
+  /// After calling [stop], the dev server cannot be restarted.
+  ///
+  /// This can be called internally if the server process is killed or if the
+  /// watcher stops watching.
+  Future<void> stop([ExitCode exitCode = ExitCode.success]) async {
+    if (isCompleted) {
+      return;
+    }
+
+    if (isWatching) {
+      await _cancelWatcherSubscription();
+    }
+    if (isServerRunning) {
+      await _killServerProcess();
+    }
+
+    _exitCodeCompleter.complete(exitCode);
+  }
+
+  /// Regenerates the dev server code and sends a hot reload signal to the
+  /// server.
+  Future<void> reload() async {
+    if (isCompleted || !isServerRunning || _isReloading) return;
+    return _reload();
   }
 }
+
+/// {@template dart_frog_dev_server_exception}
+/// Exception thrown when the dev server fails to start.
+/// {@endtemplate}
+class DartFrogDevServerException implements Exception {
+  /// {@macro dart_frog_dev_server_exception}
+  DartFrogDevServerException(this.message);
+
+  /// The exception message.
+  final String message;
+}

packages/dart_frog_cli/lib/src/runtime_compatibility.dart

@@ -15,7 +15,7 @@ class DartFrogCompatibilityException implements Exception {
   /// {@macro dart_frog_compatibility_exception}
   const DartFrogCompatibilityException(this.message);
 
-  /// The error message.
+  /// The exception message.
   final String message;
 
   @override

packages/dart_frog_cli/test/src/commands/dev/dev_test.dart

@@ -65,8 +65,9 @@ void main() {
     });
 
     test('run the dev server with the given parameters', () async {
-      when(() => runner.start()).thenAnswer(
-        (invocation) => Future.value(ExitCode.success),
+      when(() => runner.start()).thenAnswer((_) => Future.value());
+      when(() => runner.exitCode).thenAnswer(
+        (_) => Future.value(ExitCode.success),
       );
 
       when(() => argResults['port']).thenReturn('1234');
@@ -126,11 +127,36 @@ void main() {
         logger: logger,
       )..testArgResults = argResults;
 
-      when(() => runner.start()).thenAnswer(
-        (invocation) => Future.value(ExitCode.software),
+      when(() => runner.start()).thenAnswer((_) => Future.value());
+      when(() => runner.exitCode).thenAnswer(
+        (_) => Future.value(ExitCode.unavailable),
       );
 
+      await expectLater(command.run(), completion(ExitCode.unavailable.code));
+    });
+
+    test('fails if dev server runner fails on start', () async {
+      final command = DevCommand(
+        generator: (_) async => generator,
+        ensureRuntimeCompatibility: (_) {},
+        devServerRunnerBuilder: ({
+          required logger,
+          required port,
+          required devServerBundleGenerator,
+          required dartVmServicePort,
+          required workingDirectory,
+        }) {
+          return runner;
+        },
+        logger: logger,
+      )..testArgResults = argResults;
+
+      when(() => runner.start()).thenAnswer((_) async {
+        throw DartFrogDevServerException('oops');
+      });
+
       await expectLater(command.run(), completion(ExitCode.software.code));
+      verify(() => logger.err('oops')).called(1);
     });
   });
 }