flwr-nightly 1.13.0.dev20241111__py3-none-any.whl → 1.14.0.dev20241126__py3-none-any.whl

flwr/server/superlink/linkstate/utils.py

@@ -15,15 +15,23 @@
 """Utility functions for State."""
 
 
+from logging import ERROR
 from os import urandom
+from typing import Optional, Union
+from uuid import UUID, uuid4
 
-from flwr.common import ConfigsRecord, Context, serde
-from flwr.common.constant import Status, SubStatus
+from flwr.common import ConfigsRecord, Context, log, now, serde
+from flwr.common.constant import ErrorCode, Status, SubStatus
 from flwr.common.typing import RunStatus
-from flwr.proto.message_pb2 import Context as ProtoContext  # pylint: disable=E0611
 
 # pylint: disable=E0611
+from flwr.proto.error_pb2 import Error
+from flwr.proto.message_pb2 import Context as ProtoContext
+from flwr.proto.node_pb2 import Node
 from flwr.proto.recordset_pb2 import ConfigsRecord as ProtoConfigsRecord
+from flwr.proto.task_pb2 import Task, TaskIns, TaskRes
+
+# pylint: enable=E0611
 
 NODE_UNAVAILABLE_ERROR_REASON = (
     "Error: Node Unavailable - The destination node is currently unavailable. "
@@ -34,12 +42,22 @@ VALID_RUN_STATUS_TRANSITIONS = {
     (Status.PENDING, Status.STARTING),
     (Status.STARTING, Status.RUNNING),
     (Status.RUNNING, Status.FINISHED),
+    # Any non-FINISHED status can transition to FINISHED
+    (Status.PENDING, Status.FINISHED),
+    (Status.STARTING, Status.FINISHED),
 }
 VALID_RUN_SUB_STATUSES = {
     SubStatus.COMPLETED,
     SubStatus.FAILED,
     SubStatus.STOPPED,
 }
+MESSAGE_UNAVAILABLE_ERROR_REASON = (
+    "Error: Message Unavailable - The requested message could not be found in the "
+    "database. It may have expired due to its TTL or never existed."
+)
+REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON = (
+    "Error: Reply Message Unavailable - The reply message has expired."
+)
 
 
 def generate_rand_int_from_bytes(num_bytes: int) -> int:
@@ -170,6 +188,14 @@ def is_valid_transition(current_status: RunStatus, new_status: RunStatus) -> boo
     bool
         True if the transition is valid, False otherwise.
     """
+    # Transition to FINISHED from a non-RUNNING status is only allowed
+    # if the sub-status is not COMPLETED
+    if (
+        current_status.status in [Status.PENDING, Status.STARTING]
+        and new_status.status == Status.FINISHED
+    ):
+        return new_status.sub_status != SubStatus.COMPLETED
+
     return (
         current_status.status,
         new_status.status,
@@ -197,3 +223,167 @@ def has_valid_sub_status(status: RunStatus) -> bool:
     if status.status == Status.FINISHED:
         return status.sub_status in VALID_RUN_SUB_STATUSES
     return status.sub_status == ""
+
+
+def create_taskres_for_unavailable_taskins(taskins_id: Union[str, UUID]) -> TaskRes:
+    """Generate a TaskRes with a TaskIns unavailable error.
+
+    Parameters
+    ----------
+    taskins_id : Union[str, UUID]
+        The ID of the unavailable TaskIns.
+
+    Returns
+    -------
+    TaskRes
+        A TaskRes with an error code MESSAGE_UNAVAILABLE to indicate that the
+        inquired TaskIns ID cannot be found (due to non-existence or expiration).
+    """
+    current_time = now().timestamp()
+    return TaskRes(
+        task_id=str(uuid4()),
+        group_id="",  # Unknown group ID
+        run_id=0,  # Unknown run ID
+        task=Task(
+            # This function is only called by SuperLink, and thus it's the producer.
+            producer=Node(node_id=0, anonymous=False),
+            consumer=Node(node_id=0, anonymous=False),
+            created_at=current_time,
+            ttl=0,
+            ancestry=[str(taskins_id)],
+            task_type="",  # Unknown message type
+            error=Error(
+                code=ErrorCode.MESSAGE_UNAVAILABLE,
+                reason=MESSAGE_UNAVAILABLE_ERROR_REASON,
+            ),
+        ),
+    )
+
+
+def create_taskres_for_unavailable_taskres(ref_taskins: TaskIns) -> TaskRes:
+    """Generate a TaskRes with a reply message unavailable error from a TaskIns.
+
+    Parameters
+    ----------
+    ref_taskins : TaskIns
+        The reference TaskIns object.
+
+    Returns
+    -------
+    TaskRes
+        The generated TaskRes with an error code REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON,
+        indicating that the original TaskRes has expired.
+    """
+    current_time = now().timestamp()
+    ttl = ref_taskins.task.ttl - (current_time - ref_taskins.task.created_at)
+    if ttl < 0:
+        log(ERROR, "Creating TaskRes for TaskIns that exceeds its TTL.")
+        ttl = 0
+    return TaskRes(
+        task_id=str(uuid4()),
+        group_id=ref_taskins.group_id,
+        run_id=ref_taskins.run_id,
+        task=Task(
+            # This function is only called by SuperLink, and thus it's the producer.
+            producer=Node(node_id=0, anonymous=False),
+            consumer=Node(node_id=0, anonymous=False),
+            created_at=current_time,
+            ttl=ttl,
+            ancestry=[ref_taskins.task_id],
+            task_type=ref_taskins.task.task_type,
+            error=Error(
+                code=ErrorCode.REPLY_MESSAGE_UNAVAILABLE,
+                reason=REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON,
+            ),
+        ),
+    )
+
+
+def has_expired(task_ins_or_res: Union[TaskIns, TaskRes], current_time: float) -> bool:
+    """Check if the TaskIns/TaskRes has expired."""
+    return task_ins_or_res.task.ttl + task_ins_or_res.task.created_at < current_time
+
+
+def verify_taskins_ids(
+    inquired_taskins_ids: set[UUID],
+    found_taskins_dict: dict[UUID, TaskIns],
+    current_time: Optional[float] = None,
+    update_set: bool = True,
+) -> dict[UUID, TaskRes]:
+    """Verify found TaskIns and generate error TaskRes for invalid ones.
+
+    Parameters
+    ----------
+    inquired_taskins_ids : set[UUID]
+        Set of TaskIns IDs for which to generate error TaskRes if invalid.
+    found_taskins_dict : dict[UUID, TaskIns]
+        Dictionary containing all found TaskIns indexed by their IDs.
+    current_time : Optional[float] (default: None)
+        The current time to check for expiration. If set to `None`, the current time
+        will automatically be set to the current timestamp using `now().timestamp()`.
+    update_set : bool (default: True)
+        If True, the `inquired_taskins_ids` will be updated to remove invalid ones,
+        by default True.
+
+    Returns
+    -------
+    dict[UUID, TaskRes]
+        A dictionary of error TaskRes indexed by the corresponding TaskIns ID.
+    """
+    ret_dict = {}
+    current = current_time if current_time else now().timestamp()
+    for taskins_id in list(inquired_taskins_ids):
+        # Generate error TaskRes if the task_ins doesn't exist or has expired
+        taskins = found_taskins_dict.get(taskins_id)
+        if taskins is None or has_expired(taskins, current):
+            if update_set:
+                inquired_taskins_ids.remove(taskins_id)
+            taskres = create_taskres_for_unavailable_taskins(taskins_id)
+            ret_dict[taskins_id] = taskres
+    return ret_dict
+
+
+def verify_found_taskres(
+    inquired_taskins_ids: set[UUID],
+    found_taskins_dict: dict[UUID, TaskIns],
+    found_taskres_list: list[TaskRes],
+    current_time: Optional[float] = None,
+    update_set: bool = True,
+) -> dict[UUID, TaskRes]:
+    """Verify found TaskRes and generate error TaskRes for invalid ones.
+
+    Parameters
+    ----------
+    inquired_taskins_ids : set[UUID]
+        Set of TaskIns IDs for which to generate error TaskRes if invalid.
+    found_taskins_dict : dict[UUID, TaskIns]
+        Dictionary containing all found TaskIns indexed by their IDs.
+    found_taskres_list : dict[TaskIns, TaskRes]
+        List of found TaskRes to be verified.
+    current_time : Optional[float] (default: None)
+        The current time to check for expiration. If set to `None`, the current time
+        will automatically be set to the current timestamp using `now().timestamp()`.
+    update_set : bool (default: True)
+        If True, the `inquired_taskins_ids` will be updated to remove ones
+        that have a TaskRes, by default True.
+
+    Returns
+    -------
+    dict[UUID, TaskRes]
+        A dictionary of TaskRes indexed by the corresponding TaskIns ID.
+    """
+    ret_dict: dict[UUID, TaskRes] = {}
+    current = current_time if current_time else now().timestamp()
+    for taskres in found_taskres_list:
+        taskins_id = UUID(taskres.task.ancestry[0])
+        if update_set:
+            inquired_taskins_ids.remove(taskins_id)
+        # Check if the TaskRes has expired
+        if has_expired(taskres, current):
+            # No need to insert the error TaskRes
+            taskres = create_taskres_for_unavailable_taskres(
+                found_taskins_dict[taskins_id]
+            )
+            taskres.task.delivered_at = now().isoformat()
+        ret_dict[taskins_id] = taskres
+    return ret_dict

flwr/simulation/app.py

@@ -14,12 +14,9 @@
 # ==============================================================================
 """Flower Simulation process."""
 
-
 import argparse
 import sys
-from logging import DEBUG, ERROR, INFO, WARN
-from os.path import isfile
-from pathlib import Path
+from logging import DEBUG, ERROR, INFO
 from queue import Queue
 from time import sleep
 from typing import Optional
@@ -27,6 +24,7 @@ from typing import Optional
 from flwr.cli.config_utils import get_fab_metadata
 from flwr.cli.install import install_from_fab
 from flwr.common import EventType
+from flwr.common.args import add_args_flwr_app_common
 from flwr.common.config import (
     get_flwr_dir,
     get_fused_config_from_dir,
@@ -34,7 +32,11 @@ from flwr.common.config import (
     get_project_dir,
     unflatten_dict,
 )
-from flwr.common.constant import Status, SubStatus
+from flwr.common.constant import (
+    SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS,
+    Status,
+    SubStatus,
+)
 from flwr.common.logger import (
     log,
     mirror_output_to_queue,
@@ -71,102 +73,38 @@ def flwr_simulation() -> None:
     log_queue: Queue[Optional[str]] = Queue()
     mirror_output_to_queue(log_queue)
 
-    parser = argparse.ArgumentParser(
-        description="Run a Flower Simulation",
-    )
-    parser.add_argument(
-        "--superlink",
-        type=str,
-        help="Address of SuperLink's SimulationIO API",
-    )
-    parser.add_argument(
-        "--run-once",
-        action="store_true",
-        help="When set, this process will start a single simulation "
-        "for a pending Run. If no pending run the process will exit. ",
-    )
-    parser.add_argument(
-        "--flwr-dir",
-        default=None,
-        help="""The path containing installed Flower Apps.
-    By default, this value is equal to:
-
-        - `$FLWR_HOME/` if `$FLWR_HOME` is defined
-        - `$XDG_DATA_HOME/.flwr/` if `$XDG_DATA_HOME` is defined
-        - `$HOME/.flwr/` in all other cases
-    """,
-    )
-    parser.add_argument(
-        "--insecure",
-        action="store_true",
-        help="Run the server without HTTPS, regardless of whether certificate "
-        "paths are provided. By default, the server runs with HTTPS enabled. "
-        "Use this flag only if you understand the risks.",
-    )
-    parser.add_argument(
-        "--root-certificates",
-        metavar="ROOT_CERT",
-        type=str,
-        help="Specifies the path to the PEM-encoded root certificate file for "
-        "establishing secure HTTPS connections.",
-    )
-    args = parser.parse_args()
+    args = _parse_args_run_flwr_simulation().parse_args()
 
     log(INFO, "Starting Flower Simulation")
-    certificates = _try_obtain_certificates(args)
+
+    if not args.insecure:
+        log(
+            ERROR,
+            "`flwr-simulation` does not support TLS yet. "
+            "Please use the '--insecure' flag.",
+        )
+        sys.exit(1)
 
     log(
         DEBUG,
-        "Staring isolated `Simulation` connected to SuperLink DriverAPI at %s",
-        args.superlink,
+        "Starting isolated `Simulation` connected to SuperLink SimulationAppIo API "
+        "at %s",
+        args.simulationio_api_address,
     )
     run_simulation_process(
-        superlink=args.superlink,
+        simulationio_api_address=args.simulationio_api_address,
         log_queue=log_queue,
         run_once=args.run_once,
         flwr_dir_=args.flwr_dir,
-        certificates=certificates,
+        certificates=None,
     )
 
     # Restore stdout/stderr
     restore_output()
 
 
-def _try_obtain_certificates(
-    args: argparse.Namespace,
-) -> Optional[bytes]:
-
-    if args.insecure:
-        if args.root_certificates is not None:
-            sys.exit(
-                "Conflicting options: The '--insecure' flag disables HTTPS, "
-                "but '--root-certificates' was also specified. Please remove "
-                "the '--root-certificates' option when running in insecure mode, "
-                "or omit '--insecure' to use HTTPS."
-            )
-        log(
-            WARN,
-            "Option `--insecure` was set. Starting insecure HTTP channel to %s.",
-            args.superlink,
-        )
-        root_certificates = None
-    else:
-        # Load the certificates if provided, or load the system certificates
-        if not isfile(args.root_certificates):
-            sys.exit("Path argument `--root-certificates` does not point to a file.")
-        root_certificates = Path(args.root_certificates).read_bytes()
-        log(
-            DEBUG,
-            "Starting secure HTTPS channel to %s "
-            "with the following certificates: %s.",
-            args.superlink,
-            args.root_certificates,
-        )
-    return root_certificates
-
-
 def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R0915
-    superlink: str,
+    simulationio_api_address: str,
     log_queue: Queue[Optional[str]],
     run_once: bool,
     flwr_dir_: Optional[str] = None,
@@ -174,7 +112,7 @@ def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R09
 ) -> None:
     """Run Flower Simulation process."""
     conn = SimulationIoConnection(
-        simulationio_service_address=superlink,
+        simulationio_service_address=simulationio_api_address,
         root_certificates=certificates,
     )
 
@@ -260,7 +198,7 @@ def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R09
                 )
             backend_config: BackendConfig = fed_opt.get("backend", {})
             verbose: bool = fed_opt.get("verbose", False)
-            enable_tf_gpu_growth: bool = fed_opt.get("enable_tf_gpu_growth", True)
+            enable_tf_gpu_growth: bool = fed_opt.get("enable_tf_gpu_growth", False)
 
             # Launch the simulation
             _run_simulation(
@@ -292,6 +230,12 @@ def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R09
             run_status = RunStatus(Status.FINISHED, SubStatus.FAILED, str(ex))
 
         finally:
+            # Stop log uploader for this run and upload final logs
+            if log_uploader:
+                stop_log_uploader(log_queue, log_uploader)
+                log_uploader = None
+
+            # Update run status
             if run_status:
                 run_status_proto = run_status_to_proto(run_status)
                 conn._stub.UpdateRunStatus(
@@ -300,11 +244,28 @@ def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R09
                     )
                 )
 
-            # Stop log uploader for this run
-            if log_uploader:
-                stop_log_uploader(log_queue, log_uploader)
-                log_uploader = None
-
         # Stop the loop if `flwr-simulation` is expected to process a single run
         if run_once:
             break
+
+
+def _parse_args_run_flwr_simulation() -> argparse.ArgumentParser:
+    """Parse flwr-simulation command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Run a Flower Simulation",
+    )
+    parser.add_argument(
+        "--simulationio-api-address",
+        default=SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS,
+        type=str,
+        help="Address of SuperLink's SimulationIO API (IPv4, IPv6, or a domain name)."
+        f"By default, it is set to {SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS}.",
+    )
+    parser.add_argument(
+        "--run-once",
+        action="store_true",
+        help="When set, this process will start a single simulation "
+        "for a pending Run. If no pending run the process will exit. ",
+    )
+    add_args_flwr_app_common(parser=parser)
+    return parser

flwr/simulation/legacy_app.py

@@ -30,7 +30,12 @@ from ray.util.scheduling_strategies import NodeAffinitySchedulingStrategy
 from flwr.client import ClientFnExt
 from flwr.common import EventType, event
 from flwr.common.constant import NODE_ID_NUM_BYTES
-from flwr.common.logger import log, set_logger_propagation, warn_unsupported_feature
+from flwr.common.logger import (
+    log,
+    set_logger_propagation,
+    warn_deprecated_feature,
+    warn_unsupported_feature,
+)
 from flwr.server.client_manager import ClientManager
 from flwr.server.history import History
 from flwr.server.server import Server, init_defaults, run_fl
@@ -108,6 +113,11 @@ def start_simulation(
 ) -> History:
     """Start a Ray-based Flower simulation server.
 
+    Warning
+    -------
+    This function is deprecated since 1.13.0. Use :code: `flwr run` to start a Flower
+    simulation.
+
     Parameters
     ----------
     client_fn : ClientFnExt
@@ -183,6 +193,16 @@ def start_simulation(
         Object containing metrics from training.
     """  # noqa: E501
     # pylint: disable-msg=too-many-locals
+    msg = (
+        "flwr.simulation.start_simulation() is deprecated."
+        "\n\tInstead, use the `flwr run` CLI command to start a local simulation "
+        "in your Flower app, as shown for example below:"
+        "\n\n\t\t$ flwr new  # Create a new Flower app from a template"
+        "\n\n\t\t$ flwr run  # Run the Flower app in Simulation Mode"
+        "\n\n\tUsing `start_simulation()` is deprecated."
+    )
+    warn_deprecated_feature(name=msg)
+
     event(
         EventType.START_SIMULATION_ENTER,
         {"num_clients": len(clients_ids) if clients_ids is not None else num_clients},

flwr/simulation/run_simulation.py

@@ -123,13 +123,8 @@ def run_simulation_from_cli() -> None:
     fused_config = get_fused_config_from_dir(app_path, override_config)
 
     # Create run
-    run = Run(
-        run_id=run_id,
-        fab_id="",
-        fab_version="",
-        fab_hash="",
-        override_config=override_config,
-    )
+    run = Run.create_empty(run_id)
+    run.override_config = override_config
 
     _run_simulation(
         server_app_attr=server_app_attr,
@@ -333,14 +328,10 @@ def _main_loop(
     try:
         # Register run
         log(DEBUG, "Pre-registering run with id %s", run.run_id)
-        init_status = RunStatus(Status.RUNNING, "", "")
-        state_factory.state().run_ids[run.run_id] = RunRecord(  # type: ignore
-            run=run,
-            status=init_status,
-            starting_at=now().isoformat(),
-            running_at=now().isoformat(),
-            finished_at="",
-        )
+        run.status = RunStatus(Status.RUNNING, "", "")
+        run.starting_at = now().isoformat()
+        run.running_at = run.starting_at
+        state_factory.state().run_ids[run.run_id] = RunRecord(run=run)  # type: ignore
 
         if server_app_run_config is None:
             server_app_run_config = {}
@@ -457,9 +448,7 @@ def _run_simulation(
     # If no `Run` object is set, create one
     if run is None:
         run_id = generate_rand_int_from_bytes(RUN_ID_NUM_BYTES)
-        run = Run(
-            run_id=run_id, fab_id="", fab_version="", fab_hash="", override_config={}
-        )
+        run = Run.create_empty(run_id=run_id)
 
     args = (
         num_supernodes,

flwr/simulation/simulationio_connection.py

@@ -20,7 +20,7 @@ from typing import Optional, cast
 
 import grpc
 
-from flwr.common.constant import SIMULATIONIO_API_DEFAULT_ADDRESS
+from flwr.common.constant import SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.proto.simulationio_pb2_grpc import SimulationIoStub  # pylint: disable=E0611
@@ -41,7 +41,7 @@ class SimulationIoConnection:
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        simulationio_service_address: str = SIMULATIONIO_API_DEFAULT_ADDRESS,
+        simulationio_service_address: str = SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS,
         root_certificates: Optional[bytes] = None,
     ) -> None:
         self._addr = simulationio_service_address

flwr/superexec/deployment.py

@@ -21,8 +21,13 @@ from typing import Optional
 
 from typing_extensions import override
 
+from flwr.cli.config_utils import get_fab_metadata
 from flwr.common import ConfigsRecord, Context, RecordSet
-from flwr.common.constant import SERVERAPPIO_API_DEFAULT_ADDRESS, Status, SubStatus
+from flwr.common.constant import (
+    SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS,
+    Status,
+    SubStatus,
+)
 from flwr.common.logger import log
 from flwr.common.typing import Fab, RunStatus, UserConfig
 from flwr.server.superlink.ffs import Ffs
@@ -37,7 +42,7 @@ class DeploymentEngine(Executor):
 
     Parameters
     ----------
-    superlink: str (default: "0.0.0.0:9091")
+    serverappio_api_address: str (default: "127.0.0.1:9091")
         Address of the SuperLink to connect to.
     root_certificates: Optional[str] (default: None)
         Specifies the path to the PEM-encoded root certificate file for
@@ -48,11 +53,11 @@ class DeploymentEngine(Executor):
 
     def __init__(
         self,
-        superlink: str = SERVERAPPIO_API_DEFAULT_ADDRESS,
+        serverappio_api_address: str = SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS,
         root_certificates: Optional[str] = None,
         flwr_dir: Optional[str] = None,
     ) -> None:
-        self.superlink = superlink
+        self.serverappio_api_address = serverappio_api_address
         if root_certificates is None:
             self.root_certificates = None
             self.root_certificates_bytes = None
@@ -109,7 +114,7 @@ class DeploymentEngine(Executor):
         if superlink_address := config.get("superlink"):
             if not isinstance(superlink_address, str):
                 raise ValueError("The `superlink` value should be of type `str`.")
-            self.superlink = superlink_address
+            self.serverappio_api_address = superlink_address
         if root_certificates := config.get("root-certificates"):
             if not isinstance(root_certificates, str):
                 raise ValueError(
@@ -132,9 +137,10 @@ class DeploymentEngine(Executor):
             raise RuntimeError(
                 f"FAB ({fab.hash_str}) hash from request doesn't match contents"
             )
+        fab_id, fab_version = get_fab_metadata(fab.content)
 
         run_id = self.linkstate.create_run(
-            None, None, fab_hash, override_config, ConfigsRecord()
+            fab_id, fab_version, fab_hash, override_config, ConfigsRecord()
         )
         return run_id
 

flwr/superexec/exec_servicer.py

@@ -22,18 +22,25 @@ from typing import Any
 
 import grpc
 
+from flwr.common import now
 from flwr.common.constant import LOG_STREAM_INTERVAL, Status
 from flwr.common.logger import log
-from flwr.common.serde import configs_record_from_proto, user_config_from_proto
+from flwr.common.serde import (
+    configs_record_from_proto,
+    run_to_proto,
+    user_config_from_proto,
+)
 from flwr.proto import exec_pb2_grpc  # pylint: disable=E0611
 from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    ListRunsRequest,
+    ListRunsResponse,
     StartRunRequest,
     StartRunResponse,
     StreamLogsRequest,
     StreamLogsResponse,
 )
 from flwr.server.superlink.ffs.ffs_factory import FfsFactory
-from flwr.server.superlink.linkstate import LinkStateFactory
+from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
 
 from .executor import Executor
 
@@ -105,3 +112,25 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
                 context.cancel()
 
             time.sleep(LOG_STREAM_INTERVAL)  # Sleep briefly to avoid busy waiting
+
+    def ListRuns(
+        self, request: ListRunsRequest, context: grpc.ServicerContext
+    ) -> ListRunsResponse:
+        """Handle `flwr ls` command."""
+        log(INFO, "ExecServicer.List")
+        state = self.linkstate_factory.state()
+
+        # Handle `flwr ls --runs`
+        if not request.HasField("run_id"):
+            return _create_list_runs_response(state.get_run_ids(), state)
+        # Handle `flwr ls --run-id <run_id>`
+        return _create_list_runs_response({request.run_id}, state)
+
+
+def _create_list_runs_response(run_ids: set[int], state: LinkState) -> ListRunsResponse:
+    """Create response for `flwr ls --runs` and `flwr ls --run-id <run_id>`."""
+    run_dict = {run_id: state.get_run(run_id) for run_id in run_ids}
+    return ListRunsResponse(
+        run_dict={run_id: run_to_proto(run) for run_id, run in run_dict.items() if run},
+        now=now().isoformat(),
+    )