feat: RelicApp now supports hot-reload (#226)

Adds hot-reload support to `RelicApp`

Author: nielsenko

lib/src/relic_server.dart

@@ -28,13 +28,8 @@ class RelicServer {
   ///
   /// Only one handler can be mounted at a time.
   Future<void> mountAndStart(final Handler handler) async {
-    if (_handler != null) {
-      throw StateError(
-        'Relic server already has a handler mounted.',
-      );
-    }
     _handler = _wrapHandlerWithMiddleware(handler);
-    await _startListening();
+    if (_subscription == null) await _startListening();
   }
 
   /// Close the server

lib/src/router/relic_app.dart

@@ -0,0 +1,147 @@
+part of 'router.dart';
+
+/// The main application class for a Relic web server.
+///
+/// [RelicApp] extends [RelicRouter] and provides a convenient way to create,
+/// configure, and run a Relic HTTP server.
+final class RelicApp implements RelicRouter {
+  RelicServer? _server;
+  StreamSubscription? _reloadSubscription;
+  var delegate = RelicRouter();
+  final _setup = <RouterInjectable>[];
+
+  /// Creates and starts a [RelicServer] with the configured routes.
+  ///
+  /// The [adapterFactory] is a function that returns an [Adapter] for handling
+  /// HTTP requests. This can be a synchronous function or an async function.
+  /// The adapter factory pattern allows for deferred initialization of server
+  /// resources.
+  ///
+  /// Returns a [Future] that completes with the running [RelicServer] instance.
+  ///
+  /// [RelicApp] instances supports hot-reload. They will re-configure the internal
+  /// router on hot-reload. This allows adding and removing routes despite `main`
+  /// not being re-run.
+  ///
+  /// Example:
+  /// ```dart
+  /// final app = RelicApp()
+  ///   ..get('/', (ctx) => ctx.ok('Hello!'));
+  ///
+  /// final adaptorFactory = () => IOAdapter.bind(InternetAddress.loopbackIPv4, port: 8080);
+  /// final server = await app.run(adapterFactory);
+  ///
+  /// // later .. when done
+  ///
+  /// await app.close();
+  /// ```
+  ///
+  /// Check out [RelicAppIOServeEx.serve] if you are using `dart:io` to avoid
+  /// specifying [adapterFactory] explicitly.
+  Future<RelicServer> run(
+    final FutureOr<Adapter> Function() adapterFactory,
+  ) async {
+    if (_server != null) throw StateError('Cannot call run twice');
+    _server = RelicServer(await adapterFactory());
+    await _init();
+    _reloadSubscription = await _hotReloader.register(this);
+    return _server!;
+  }
+
+  Future<void> close() async {
+    await _reloadSubscription?.cancel();
+    await _server?.close();
+  }
+
+  Future<void> _init() async {
+    await _server!.mountAndStart(delegate.asHandler);
+  }
+
+  Future<void> _reload() async {
+    await _rebuild();
+    await _init();
+  }
+
+  Future<void> _rebuild() async {
+    delegate = RelicRouter();
+    for (final injectable in _setup) {
+      delegate.inject(injectable);
+    }
+  }
+
+  void _injectAndTrack(final RouterInjectable injectable) {
+    delegate.inject(injectable);
+    _setup.add(injectable);
+  }
+
+  @override
+  void add(final Method method, final String path, final Handler route) =>
+      inject(_Injectable((final r) => r.add(method, path, route)));
+
+  @override
+  void attach(final String path, final RelicRouter subRouter) =>
+      inject(_Injectable((final r) => r.attach(path, subRouter)));
+
+  @override
+  void use(final String path, final Middleware map) =>
+      inject(_Injectable((final r) => r.use(path, map)));
+
+  @override
+  void inject(final RouterInjectable injectable) => _injectAndTrack(injectable);
+
+  @override
+  Handler? get fallback => delegate.fallback;
+
+  @override
+  set fallback(final Handler? value) =>
+      inject(_Injectable((final r) => r.fallback = value));
+
+  @override
+  PathTrie<_RouterEntry<Handler>> get _allRoutes => delegate._allRoutes;
+
+  @override
+  bool get isEmpty => delegate.isEmpty;
+
+  @override
+  LookupResult<Handler> lookup(final Method method, final String path) =>
+      delegate.lookup(method, path);
+}
+
+final class _Injectable implements RouterInjectable {
+  final void Function(RelicRouter) setup;
+
+  _Injectable(this.setup);
+
+  @override
+  void injectIn(final RelicRouter owner) => setup(owner);
+}
+
+class _HotReloader {
+  static final Future<Stream<void>?> _reloadStream = _init();
+
+  static Future<Stream<void>?> _init() async {
+    final wsUri = (await Service.getInfo()).serverWebSocketUri;
+    if (wsUri != null) {
+      final vmService = await vmi.vmServiceConnectUri(wsUri.toString());
+      const streamId = vm.EventStreams.kIsolate;
+      return vmService.onIsolateEvent
+          .asBroadcastStream(
+              onListen: (final _) => vmService.streamListen(streamId),
+              onCancel: (final _) => vmService.streamCancel(streamId))
+          .where((final e) => e.kind == vm.EventKind.kIsolateReload);
+    }
+    return null; // no vm service available
+  }
+
+  Future<StreamSubscription?> register(final RelicApp app) async {
+    final reloadStream = await _reloadStream;
+    if (reloadStream != null) {
+      return reloadStream
+          .asyncMap((final _) => app._reload())
+          .listen((final _) {});
+    }
+    return null;
+  }
+}
+
+final _hotReloader = _HotReloader();

lib/src/router/router.dart

@@ -1,9 +1,15 @@
 import 'dart:async';
+import 'dart:developer';
+
+import 'package:vm_service/vm_service.dart' as vm;
+import 'package:vm_service/vm_service_io.dart' as vmi;
 
 import '../../relic.dart';
 import 'normalized_path.dart';
 import 'path_trie.dart';
 
+part 'relic_app.dart';
+
 /// A wrapper around a fixed-length list used for mapping between method and value
 /// for each registered path.
 extension type _RouterEntry<T extends Object>._(List<T?> _routeByVerb)
@@ -36,6 +42,15 @@ extension<T extends Object> on _RouterEntry<T>? {
   _RouterEntry<T> get orNew => this ?? _RouterEntry<T>();
 }
 
+/// Interface for objects that can be injected in others. This allows
+/// an object to delegate setup to another object.
+///
+/// Used by [Router.inject] which takes an [InjectableIn<Router<T>>].
+abstract interface class InjectableIn<T> {
+  /// Overwrite this to define how to inject this object in [owner].
+  void injectIn(final T owner);
+}
+
 /// A URL router that maps path patterns to values of type [T].
 ///
 /// Supports static paths (e.g., `/users/profile`) and paths with named parameters
@@ -113,6 +128,11 @@ final class Router<T extends Object> {
     _allRoutes.attach(NormalizedPath(path), subRouter._allRoutes);
   }
 
+  /// Injects an [injectable] into the router. Unlike [add] it allows
+  /// the [injectable] object to determine how to be mounted on the router.
+  void inject(final InjectableIn<Router<T>> injectable) =>
+      injectable.injectIn(this);
+
   /// Looks up a route matching the provided [path].
   ///
   /// The input [path] string is normalized before lookup. Static routes are
@@ -244,39 +264,4 @@ typedef RelicRouter = Router<Handler>;
 ///   ResponseContext delete(final NewContext ctx) { }
 /// }
 /// ```
-abstract interface class RouterInjectable {
-  void injectIn(final RelicRouter router);
-}
-
-/// The main application class for a Relic web server.
-///
-/// [RelicApp] extends [RelicRouter] and provides a convenient way to create,
-/// configure, and run a Relic HTTP server.
-final class RelicApp extends RelicRouter {
-  /// Creates and starts a [RelicServer] with the configured routes.
-  ///
-  /// The [adapterFactory] is a function that returns an [Adapter] for handling
-  /// HTTP requests. This can be a synchronous function or an async function.
-  /// The adapter factory pattern allows for deferred initialization of server
-  /// resources.
-  ///
-  /// Returns a [Future] that completes with the running [RelicServer] instance.
-  ///
-  /// Example:
-  /// ```dart
-  /// final app = RelicApp()
-  ///   ..get('/', (ctx) => ctx.ok('Hello!'));
-  ///
-  /// final server = await app.run(adapterFactory);
-  /// ```
-  ///
-  /// Check out [RelicAppIOServeEx.serve] if you are using `dart:io` to avoid
-  /// specifying [adapterFactory] explicitly.
-  Future<RelicServer> run(
-    final FutureOr<Adapter> Function() adapterFactory,
-  ) async {
-    final server = RelicServer(await adapterFactory());
-    await server.mountAndStart(call);
-    return server;
-  }
-}
+typedef RouterInjectable = InjectableIn<RelicRouter>;

lib/src/router/router_handler_extension.dart

@@ -27,8 +27,4 @@ extension RouterHandlerEx on RelicRouter {
   FutureOr<HandledContext> call(final NewContext ctx) =>
       const Pipeline().addMiddleware(routeWith(this)).addHandler(
           fallback ?? respondWith((final _) => Response.notFound()))(ctx);
-
-  /// Injects a handler object into the router. Unlike [add] it allows
-  /// the [handler] object to determine how to be mounted on the router.
-  void inject(final RouterInjectable handler) => handler.injectIn(this);
 }

pubspec.yaml

@@ -17,6 +17,7 @@ dependencies:
   path: ^1.8.3
   stack_trace: ^1.10.0
   stream_channel: ^2.1.1
+  vm_service: ^15.0.0
   web_socket: ^1.0.1
   web_socket_channel: ^3.0.3
 
@@ -31,7 +32,7 @@ dev_dependencies:
   routingkit: ^5.1.2
   serverpod_lints: ^2.8.0
   spanner: ^1.0.5
-  test: ^1.25.5
+  test: ^1.25.10
   test_descriptor: ^2.0.1
   # The following are not used directly, but are included transitively.
   # Due to bad semver hygiene we need to bound the versions higher than

test/relic_server_test.dart

@@ -45,19 +45,5 @@ void main() {
       await server.mountAndStart(asyncHandler);
       expect(delayedResponse, completion(equals('Hello from /')));
     });
-
-    test(
-        'when a handler is already mounted '
-        'then mounting another handler throws a StateError', () async {
-      await server.mountAndStart((final _) => throw UnimplementedError());
-      expect(
-        () => server.mountAndStart((final _) => throw UnimplementedError()),
-        throwsStateError,
-      );
-      expect(
-        () => server.mountAndStart((final _) => throw UnimplementedError()),
-        throwsStateError,
-      );
-    });
   });
 }