fix(framework): Report clientapp appio communication failures as errors

framework/docs/source/ref-exit-codes/250.rst

@@ -0,0 +1,24 @@
+#####################################
+ [250] CLIENTAPP_COMMUNICATION_ERROR
+#####################################
+
+*************
+ Description
+*************
+
+During a run, the internal ClientApp process could not communicate with the SuperNode
+ClientAppIo API.
+
+****************
+ How to Resolve
+****************
+
+Check the run output and the surrounding SuperNode and SuperExec process logs for the
+underlying gRPC error. By default, these processes log to stdout/stderr; in
+containerized deployments, inspect the relevant SuperNode and SuperExec pod/container
+logs.
+
+A likely cause is that the ClientApp process took too long to start, for example on a
+very slow or overloaded system, causing a timeout error. If the logs are not enough to
+diagnose the issue, contact the Flower team and include the relevant run, SuperNode, and
+SuperExec/ClientApp logs.

framework/py/flwr/common/exit/exit_code.py

@@ -35,12 +35,15 @@ class ExitCode:
     SUPERLINK_INVALID_ARGS = 104
     SUPERLINK_DATABASE_SCHEMA_MISMATCH = 105
 
-    # ServerApp-specific exit codes (200-299)
+    # ServerApp-specific exit codes (200-249)
     SERVERAPP_STRATEGY_PRECONDITION_UNMET = 200
     SERVERAPP_EXCEPTION = 201
     SERVERAPP_STRATEGY_AGGREGATION_ERROR = 202
     SERVERAPP_RUN_START_REJECTED = 203
 
+    # ClientApp-specific exit codes (250-299)
+    CLIENTAPP_COMMUNICATION_ERROR = 250
+
     # SuperNode-specific exit codes (300-399)
     SUPERNODE_REST_ADDRESS_INVALID = 300
     # SUPERNODE_NODE_AUTH_KEYS_REQUIRED = 301 --- DELETED ---
@@ -102,7 +105,7 @@ def __new__(cls) -> ExitCode:
         "SuperLink. Please refer to the documentation for guidance on how to resolve "
         "this issue."
     ),
-    # ServerApp-specific exit codes (200-299)
+    # ServerApp-specific exit codes (200-249)
     ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET: (
         "The strategy received replies that cannot be aggregated. Please ensure all "
         "replies returned by ClientApps have one `ArrayRecord` (none when replies are "
@@ -122,6 +125,10 @@ def __new__(cls) -> ExitCode:
         "run has been stopped, the run ID or FAB is invalid, or the run failed to "
         "start within the allowed time."
     ),
+    # ClientApp-specific exit codes (250-299)
+    ExitCode.CLIENTAPP_COMMUNICATION_ERROR: (
+        "The ClientApp could not communicate with the ClientAppIo API."
+    ),
     # SuperNode-specific exit codes (300-399)
     ExitCode.SUPERNODE_REST_ADDRESS_INVALID: (
         "When using the REST API, please provide `https://` or "

framework/py/flwr/supernode/runtime/run_clientapp.py

@@ -98,6 +98,7 @@ def run_clientapp(  # pylint: disable=R0913, R0914, R0915, R0917
     channel.subscribe(on_channel_state_change)
     heartbeat_sender = None
     runtime_env_dir = None
+    exit_code = ExitCode.SUCCESS
 
     def on_exit() -> None:
         if heartbeat_sender is not None and heartbeat_sender.is_running:
@@ -207,10 +208,11 @@ def on_exit() -> None:
             )
 
     except grpc.RpcError as e:
-        log(ERROR, "GRPC error occurred: %s", str(e))
+        log(ERROR, "gRPC error occurred: %s", str(e))
+        exit_code = ExitCode.CLIENTAPP_COMMUNICATION_ERROR
 
     flwr_exit(
-        code=ExitCode.SUCCESS,
+        code=exit_code,
         event_type=EventType.FLWR_CLIENTAPP_RUN_LEAVE,
     )
 

framework/py/flwr/supernode/runtime/run_clientapp_test.py

@@ -18,6 +18,9 @@
 import unittest
 from unittest.mock import patch
 
+import grpc
+
+from flwr.common.exit import ExitCode
 from flwr.supercore.interceptors import AppIoTokenClientInterceptor
 
 from .run_clientapp import run_clientapp
@@ -41,3 +44,25 @@ def test_run_clientapp_adds_token_client_interceptor(self) -> None:
         assert interceptors is not None
         self.assertEqual(len(interceptors), 1)
         self.assertIsInstance(interceptors[0], AppIoTokenClientInterceptor)
+
+    def test_run_clientapp_exits_nonzero_on_grpc_error(self) -> None:
+        """`run_clientapp` should not report success after AppIO gRPC failures."""
+        with (
+            patch("flwr.supernode.runtime.run_clientapp.create_channel") as channel,
+            patch("flwr.supernode.runtime.run_clientapp.HeartbeatSender"),
+            patch(
+                "flwr.supernode.runtime.run_clientapp.pull_appinputs",
+                side_effect=grpc.RpcError,
+            ),
+            patch("flwr.supernode.runtime.run_clientapp.flwr_exit") as flwr_exit,
+        ):
+            flwr_exit.side_effect = RuntimeError
+            with self.assertRaises(RuntimeError):
+                run_clientapp("127.0.0.1:9094", insecure=True, token="test-token")
+
+        channel.return_value.subscribe.assert_called_once()
+        flwr_exit.assert_called_once()
+        self.assertEqual(
+            flwr_exit.call_args.kwargs["code"],
+            ExitCode.CLIENTAPP_COMMUNICATION_ERROR,
+        )