feat: Add focus hooks with metadata

Author: mcquenji

analysis_options.yaml

@@ -14,4 +14,4 @@ linter:
     join_return_with_assignment: true
     prefer_for_elements_to_map_fromIterable: true
     null_check_on_nullable_type_parameter: true
-    # yet to be released: document_ignores: true
+    document_ignores: true

build.yaml

@@ -0,0 +1,11 @@
+targets:
+  $default:
+    builders:
+      freezed:
+        enabled: true
+        generate_for:
+          exclude:
+            - example
+        options:
+          format: true
+          explicit_to_json: true

example/pubspec.lock

@@ -5,10 +5,10 @@ packages:
     dependency: transitive
     description:
       name: args
-      sha256: bf9f5caeea8d8fe6721a9c358dd8a5c1947b27f1cfaa18b39c301273594919e6
+      sha256: d0481093c50b1da8910eb0bb301626d4d8eb7284aa739614d2b394ee09e3ea04
       url: "https://pub.dev"
     source: hosted
-    version: "2.6.0"
+    version: "2.7.0"
   async:
     dependency: transitive
     description:
@@ -77,10 +77,10 @@ packages:
     dependency: transitive
     description:
       name: ffi
-      sha256: "16ed7b077ef01ad6170a3d0c57caa4a112a38d7a2ed5602e0aca9ca6f3d98da6"
+      sha256: "289279317b4b16eb2bb7e271abccd4bf84ec9bdcbe999e278a94b804f5630418"
       url: "https://pub.dev"
     source: hosted
-    version: "2.1.3"
+    version: "2.1.4"
   fixnum:
     dependency: transitive
     description:
@@ -108,7 +108,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "1.2.3"
+    version: "1.2.4"
   flutter_test:
     dependency: "direct dev"
     description: flutter
@@ -142,18 +142,18 @@ packages:
     dependency: transitive
     description:
       name: grpc
-      sha256: "5b99b7a420937d4361ece68b798c9af8e04b5bc128a7859f2a4be87427694813"
+      sha256: "751635443218cc81d2120e566e47567d4e033a10f99de859f21b65eefcad8488"
       url: "https://pub.dev"
     source: hosted
-    version: "4.0.1"
+    version: "4.0.3"
   http:
     dependency: transitive
     description:
       name: http
-      sha256: b9c29a161230ee03d3ccf545097fccd9b87a5264228c5d348202e0f0c28f9010
+      sha256: fe7ab022b76f3034adc518fb6ea04a82387620e19977665ea18d30a1cf43442f
       url: "https://pub.dev"
     source: hosted
-    version: "1.2.2"
+    version: "1.3.0"
   http2:
     dependency: transitive
     description:
@@ -262,10 +262,10 @@ packages:
     dependency: transitive
     description:
       name: path_provider_android
-      sha256: "4adf4fd5423ec60a29506c76581bc05854c55e3a0b72d35bb28d661c9686edf2"
+      sha256: "0ca7359dad67fd7063cb2892ab0c0737b2daafd807cf1acecd62374c8fae6c12"
       url: "https://pub.dev"
     source: hosted
-    version: "2.2.15"
+    version: "2.2.16"
   path_provider_foundation:
     dependency: transitive
     description:
@@ -443,10 +443,10 @@ packages:
     dependency: transitive
     description:
       name: web
-      sha256: cd3543bd5798f6ad290ea73d210f423502e71900302dde696f8bff84bf89a1cb
+      sha256: "868d88a33d8a87b18ffc05f9f030ba328ffefba92d6c127917a2ba740f9cfe4a"
       url: "https://pub.dev"
     source: hosted
-    version: "1.1.0"
+    version: "1.1.1"
   window_manager:
     dependency: transitive
     description:
@@ -464,5 +464,5 @@ packages:
     source: hosted
     version: "1.1.0"
 sdks:
-  dart: ">=3.7.0-0 <4.0.0"
-  flutter: ">=3.24.0"
+  dart: ">=3.7.0 <4.0.0"
+  flutter: ">=3.27.0"

lib/flutter_single_instance.dart

@@ -31,6 +31,7 @@ library flutter_single_instance;
 
 export 'package:window_manager/window_manager.dart' show windowManager;
 
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 import 'package:flutter/foundation.dart';
@@ -81,6 +82,17 @@ abstract class FlutterSingleInstance {
   /// Defaults to [kDebugMode].
   static bool debugMode = kDebugMode;
 
+  /// Called before this instance is focused with metadata provided by the calling instance.
+  ///
+  /// ```dart
+  /// FlutterSingleInstance.onFocus = (metadata) {
+  ///   print("Focused instance with metadata: $metadata"); // "Focused instance with metadata: {hello: world}"
+  /// };
+  ///
+  /// FlutterSingleInstance().focus({"hello": "world"});
+  /// ```
+  static FutureOr<void> Function(Map<String, dynamic>)? onFocus;
+
   /// Retrieves the process name of the given [pid].
   /// Returns [null] if the process does not exist.
   Future<String?> getProcessName(int pid);
@@ -190,9 +202,10 @@ abstract class FlutterSingleInstance {
     return _server!.port!;
   }
 
-  /// Focuses the running instance of the app and
-  /// returns `null` if the operation was successful or an error message if it failed.
-  Future<String?> focus() async {
+  /// Focuses the running instance of the app and returns `null` if the operation was successful or an error message if it failed.
+  ///
+  /// The [metadata] parameter is passed to the focused instance's [onFocus] callback.
+  Future<String?> focus([Object? metadata]) async {
     if (_instance == null) return "No instance to focus";
     if (_server != null) return "This is the first instance";
 
@@ -213,9 +226,15 @@ abstract class FlutterSingleInstance {
         ),
       );
 
+      if (metadata == null) {
+        metadata = <String, dynamic>{};
+      }
+      final json = jsonEncode(metadata);
+      final binary = utf8.encode(json);
+
       final client = FocusServiceClient(channel);
 
-      final response = await client.focus(FocusRequest());
+      final response = await client.focus(FocusRequest(metadata: binary));
 
       if (response.success) {
         logger.finest("Instance focused");

lib/src/focus.dart

@@ -1,3 +1,5 @@
+import 'dart:convert';
+
 import 'package:flutter_single_instance/flutter_single_instance.dart';
 import 'package:flutter_single_instance/src/generated/focus.pbgrpc.dart';
 import 'package:grpc/grpc.dart';
@@ -6,11 +8,25 @@ import 'package:grpc/grpc.dart';
 class FocusService extends FocusServiceBase {
   @override
   Future<FocusResponse> focus(ServiceCall call, FocusRequest request) async {
+    // whe're still in the same package and should log with the same logger
     // ignore: invalid_use_of_protected_member
     final logger = FlutterSingleInstance().logger;
 
     logger.finest('Received focus request from another instance');
 
+    if (FlutterSingleInstance.onFocus != null) {
+      try {
+        final metadata =
+            jsonDecode(utf8.decode(request.metadata)) as Map<String, dynamic>;
+
+        await FlutterSingleInstance.onFocus!(metadata);
+
+        logger.finest('onFocus hook executed with $metadata');
+      } catch (e, s) {
+        logger.finest('Failed to run onFocus hook', e, s);
+      }
+    }
+
     try {
       await windowManager.focus();
 

lib/src/generated/focus.pb.dart

@@ -17,7 +17,7 @@ class Unsupported extends FlutterSingleInstance {
   Future<File?> getPidFile(String processName) async => null;
 
   @override
-  Future<String?> focus() async => null;
+  Future<String?> focus([Object? metadata]) async => null;
 
   @override
   Future<void> activateInstance(String processName) async {}

lib/src/generated/focus.pbjson.dart

@@ -6,7 +6,7 @@ service FocusService {
   rpc Focus(FocusRequest) returns (FocusResponse) {}
 }
 
-message FocusRequest {}
+message FocusRequest { bytes metadata = 1; }
 
 message FocusResponse {
   bool success = 1;

lib/src/unsupported.dart

@@ -11,8 +11,7 @@ platforms:
   android:
   web:
 environment:
-  sdk: ">=2.16.2 <4.0.0"
-  flutter: ">=1.17.0"
+  sdk: ">=3.0.0 <4.0.0"
 
 dependencies:
   flutter: