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

flwr/client/clientapp/app.py

@@ -15,6 +15,7 @@
 """Flower ClientApp process."""
 
 import argparse
+import sys
 import time
 from logging import DEBUG, ERROR, INFO
 from typing import Optional
@@ -26,7 +27,7 @@ from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import Context, Message
 from flwr.common.args import add_args_flwr_app_common
 from flwr.common.config import get_flwr_dir
-from flwr.common.constant import ErrorCode
+from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCode
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.common.message import Error
@@ -56,37 +57,29 @@ from .utils import get_load_client_app_fn
 
 def flwr_clientapp() -> None:
     """Run process-isolated Flower ClientApp."""
-    parser = argparse.ArgumentParser(
-        description="Run a Flower ClientApp",
-    )
-    parser.add_argument(
-        "--supernode",
-        type=str,
-        help="Address of SuperNode's ClientAppIo API",
-    )
-    parser.add_argument(
-        "--token",
-        type=int,
-        required=False,
-        help="Unique token generated by SuperNode for each ClientApp execution",
-    )
-    add_args_flwr_app_common(parser=parser)
-    args = parser.parse_args()
+    args = _parse_args_run_flwr_clientapp().parse_args()
+    if not args.insecure:
+        log(
+            ERROR,
+            "flwr-clientapp does not support TLS yet. "
+            "Please use the '--insecure' flag.",
+        )
+        sys.exit(1)
 
     log(INFO, "Starting Flower ClientApp")
-
     log(
         DEBUG,
         "Starting isolated `ClientApp` connected to SuperNode's ClientAppIo API at %s "
         "with token %s",
-        args.supernode,
+        args.clientappio_api_address,
         args.token,
     )
     run_clientapp(
-        supernode=args.supernode,
+        clientappio_api_address=args.clientappio_api_address,
         run_once=(args.token is not None),
         token=args.token,
         flwr_dir=args.flwr_dir,
+        certificates=None,
     )
 
 
@@ -96,15 +89,17 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 
 
 def run_clientapp(  # pylint: disable=R0914
-    supernode: str,
+    clientappio_api_address: str,
     run_once: bool,
     token: Optional[int] = None,
     flwr_dir: Optional[str] = None,
+    certificates: Optional[bytes] = None,
 ) -> None:
     """Run Flower ClientApp process."""
     channel = create_channel(
-        server_address=supernode,
-        insecure=True,
+        server_address=clientappio_api_address,
+        insecure=(certificates is None),
+        root_certificates=certificates,
     )
     channel.subscribe(on_channel_state_change)
 
@@ -237,3 +232,25 @@ def push_message(
     except grpc.RpcError as e:
         log(ERROR, "[PushClientAppOutputs] gRPC error occurred: %s", str(e))
         raise e
+
+
+def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
+    """Parse flwr-clientapp command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Run a Flower ClientApp",
+    )
+    parser.add_argument(
+        "--clientappio-api-address",
+        default=CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS,
+        type=str,
+        help="Address of SuperNode's ClientAppIo API (IPv4, IPv6, or a domain name)."
+        f"By default, it is set to {CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS}.",
+    )
+    parser.add_argument(
+        "--token",
+        type=int,
+        required=False,
+        help="Unique token generated by SuperNode for each ClientApp execution",
+    )
+    add_args_flwr_app_common(parser=parser)
+    return parser

flwr/client/grpc_rere_client/connection.py

@@ -41,11 +41,7 @@ from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.common.message import Message, Metadata
 from flwr.common.retry_invoker import RetryInvoker
-from flwr.common.serde import (
-    message_from_taskins,
-    message_to_taskres,
-    user_config_from_proto,
-)
+from flwr.common.serde import message_from_taskins, message_to_taskres, run_from_proto
 from flwr.common.typing import Fab, Run
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
@@ -159,6 +155,11 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     ping_thread: Optional[threading.Thread] = None
     ping_stop_event = threading.Event()
 
+    # Restrict retries to cases where the status code is UNAVAILABLE
+    retry_invoker.should_giveup = (
+        lambda e: e.code() != grpc.StatusCode.UNAVAILABLE  # type: ignore
+    )
+
     ###########################################################################
     # ping/create_node/delete_node/receive/send/get_run functions
     ###########################################################################
@@ -287,13 +288,7 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         )
 
         # Return fab_id and fab_version
-        return Run(
-            run_id,
-            get_run_response.run.fab_id,
-            get_run_response.run.fab_version,
-            get_run_response.run.fab_hash,
-            user_config_from_proto(get_run_response.run.override_config),
-        )
+        return run_from_proto(get_run_response.run)
 
     def get_fab(fab_hash: str) -> Fab:
         # Call FleetAPI

flwr/client/rest_client/connection.py

@@ -41,11 +41,7 @@ from flwr.common.constant import (
 from flwr.common.logger import log
 from flwr.common.message import Message, Metadata
 from flwr.common.retry_invoker import RetryInvoker
-from flwr.common.serde import (
-    message_from_taskins,
-    message_to_taskres,
-    user_config_from_proto,
-)
+from flwr.common.serde import message_from_taskins, message_to_taskres, run_from_proto
 from flwr.common.typing import Fab, Run
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
@@ -361,15 +357,9 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         # Send the request
         res = _request(req, GetRunResponse, PATH_GET_RUN)
         if res is None:
-            return Run(run_id, "", "", "", {})
-
-        return Run(
-            run_id,
-            res.run.fab_id,
-            res.run.fab_version,
-            res.run.fab_hash,
-            user_config_from_proto(res.run.override_config),
-        )
+            return Run.create_empty(run_id)
+
+        return run_from_proto(res.run)
 
     def get_fab(fab_hash: str) -> Fab:
         # Construct the request

flwr/client/supernode/app.py

@@ -28,8 +28,10 @@ from cryptography.hazmat.primitives.serialization import (
 )
 
 from flwr.common import EventType, event
+from flwr.common.args import try_obtain_root_certificates
 from flwr.common.config import parse_config_args
 from flwr.common.constant import (
+    CLIENTAPPIO_API_DEFAULT_SERVER_ADDRESS,
     FLEET_API_GRPC_RERE_DEFAULT_ADDRESS,
     ISOLATION_MODE_PROCESS,
     ISOLATION_MODE_SUBPROCESS,
@@ -61,10 +63,21 @@ def run_supernode() -> None:
             "Ignoring `--flwr-dir`.",
         )
 
-    root_certificates = _get_certificates(args)
+    # Exit if unsupported argument is passed by the user
+    if args.app is not None:
+        log(
+            ERROR,
+            "The `app` argument is deprecated. The SuperNode now automatically "
+            "uses the ClientApp delivered from the SuperLink. Providing the app "
+            "directory manually is no longer supported. Please remove the `app` "
+            "argument from your command.",
+        )
+        sys.exit(1)
+
+    root_certificates = try_obtain_root_certificates(args, args.superlink)
     load_fn = get_load_client_app_fn(
         default_app_ref="",
-        app_path=args.app,
+        app_path=None,
         flwr_dir=args.flwr_dir,
         multi_app=True,
     )
@@ -86,7 +99,7 @@ def run_supernode() -> None:
         ),
         flwr_path=args.flwr_dir,
         isolation=args.isolation,
-        supernode_address=args.supernode_address,
+        clientappio_api_address=args.clientappio_api_address,
     )
 
     # Graceful shutdown
@@ -126,41 +139,6 @@ def _warn_deprecated_server_arg(args: argparse.Namespace) -> None:
             args.superlink = args.server
 
 
-def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
-    """Load certificates if specified in args."""
-    # Obtain certificates
-    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 client connected to %s.",
-            args.superlink,
-        )
-        root_certificates = None
-    else:
-        # Load the certificates if provided, or load the system certificates
-        cert_path = args.root_certificates
-        if cert_path is None:
-            root_certificates = None
-        else:
-            root_certificates = Path(cert_path).read_bytes()
-        log(
-            DEBUG,
-            "Starting secure HTTPS client connected to %s "
-            "with the following certificates: %s.",
-            args.superlink,
-            cert_path,
-        )
-    return root_certificates
-
-
 def _parse_args_run_supernode() -> argparse.ArgumentParser:
     """Parse flower-supernode command line arguments."""
     parser = argparse.ArgumentParser(
@@ -171,12 +149,12 @@ def _parse_args_run_supernode() -> argparse.ArgumentParser:
         "app",
         nargs="?",
         default=None,
-        help="Specify the path of the Flower App to load and run the `ClientApp`. "
-        "The `pyproject.toml` file must be located in the root of this path. "
-        "When this argument is provided, the SuperNode will exclusively respond to "
-        "messages from the corresponding `ServerApp` by matching the FAB ID and FAB "
-        "version. An error will be raised if a message is received from any other "
-        "`ServerApp`.",
+        help=(
+            "(REMOVED) This argument is removed. The SuperNode now automatically "
+            "uses the ClientApp delivered from the SuperLink, so there is no need to "
+            "provide the app directory manually. This argument will be removed in a "
+            "future version."
+        ),
     )
     _parse_args_common(parser)
     parser.add_argument(
@@ -192,22 +170,22 @@ def _parse_args_run_supernode() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--isolation",
-        default=None,
+        default=ISOLATION_MODE_SUBPROCESS,
         required=False,
         choices=[
             ISOLATION_MODE_SUBPROCESS,
             ISOLATION_MODE_PROCESS,
         ],
-        help="Isolation mode when running a `ClientApp` (optional, possible values: "
-        "`subprocess`, `process`). By default, a `ClientApp` runs in the same process "
-        "that executes the SuperNode. Use `subprocess` to configure SuperNode to run "
-        "a `ClientApp` in a subprocess. Use `process` to indicate that a separate "
-        "independent process gets created outside of SuperNode.",
+        help="Isolation mode when running a `ClientApp` (`subprocess` by default, "
+        "possible values: `subprocess`, `process`). Use `subprocess` to configure "
+        "SuperNode to run a `ClientApp` in a subprocess. Use `process` to indicate "
+        "that a separate independent process gets created outside of SuperNode.",
     )
     parser.add_argument(
-        "--supernode-address",
-        default="0.0.0.0:9094",
-        help="Set the SuperNode gRPC server address. Defaults to `0.0.0.0:9094`.",
+        "--clientappio-api-address",
+        default=CLIENTAPPIO_API_DEFAULT_SERVER_ADDRESS,
+        help="ClientAppIo API (gRPC) server address (IPv4, IPv6, or a domain name). "
+        f"By default, it is set to {CLIENTAPPIO_API_DEFAULT_SERVER_ADDRESS}.",
     )
 
     return parser

flwr/common/args.py

@@ -16,11 +16,16 @@
 
 import argparse
 import sys
-from logging import DEBUG, WARN
+from logging import DEBUG, ERROR, WARN
 from os.path import isfile
 from pathlib import Path
 from typing import Optional
 
+from flwr.common.constant import (
+    TRANSPORT_TYPE_GRPC_ADAPTER,
+    TRANSPORT_TYPE_GRPC_RERE,
+    TRANSPORT_TYPE_REST,
+)
 from flwr.common.logger import log
 
 
@@ -44,21 +49,16 @@ def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
         "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.",
-    )
 
 
-def try_obtain_certificates(
+def try_obtain_root_certificates(
     args: argparse.Namespace,
+    grpc_server_address: str,
 ) -> Optional[bytes]:
     """Validate and return the root certificates."""
+    root_cert_path = args.root_certificates
     if args.insecure:
-        if args.root_certificates is not None:
+        if root_cert_path is not None:
             sys.exit(
                 "Conflicting options: The '--insecure' flag disables HTTPS, "
                 "but '--root-certificates' was also specified. Please remove "
@@ -67,17 +67,86 @@ def try_obtain_certificates(
             )
         log(
             WARN,
-            "Option `--insecure` was set. Starting insecure HTTP channel.",
+            "Option `--insecure` was set. Starting insecure HTTP channel to %s.",
+            grpc_server_address,
         )
         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()
+        if root_cert_path is None:
+            log(
+                WARN,
+                "Both `--insecure` and `--root-certificates` were not set. "
+                "Using system certificates.",
+            )
+            root_certificates = None
+        elif not isfile(root_cert_path):
+            log(ERROR, "Path argument `--root-certificates` does not point to a file.")
+            sys.exit(1)
+        else:
+            root_certificates = Path(root_cert_path).read_bytes()
         log(
             DEBUG,
-            "Starting secure HTTPS channel with the following certificates: %s.",
-            args.root_certificates,
+            "Starting secure HTTPS channel to %s "
+            "with the following certificates: %s.",
+            grpc_server_address,
+            root_cert_path,
         )
     return root_certificates
+
+
+def try_obtain_server_certificates(
+    args: argparse.Namespace,
+    transport_type: str,
+) -> Optional[tuple[bytes, bytes, bytes]]:
+    """Validate and return the CA cert, server cert, and server private key."""
+    if args.insecure:
+        log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
+        return None
+    # Check if certificates are provided
+    if transport_type in [TRANSPORT_TYPE_GRPC_RERE, TRANSPORT_TYPE_GRPC_ADAPTER]:
+        if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
+            if not isfile(args.ssl_ca_certfile):
+                sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
+            if not isfile(args.ssl_certfile):
+                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+            if not isfile(args.ssl_keyfile):
+                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
+            certificates = (
+                Path(args.ssl_ca_certfile).read_bytes(),  # CA certificate
+                Path(args.ssl_certfile).read_bytes(),  # server certificate
+                Path(args.ssl_keyfile).read_bytes(),  # server private key
+            )
+            return certificates
+        if args.ssl_certfile or args.ssl_keyfile or args.ssl_ca_certfile:
+            sys.exit(
+                "You need to provide valid file paths to `--ssl-certfile`, "
+                "`--ssl-keyfile`, and `—-ssl-ca-certfile` to create a secure "
+                "connection in Fleet API server (gRPC-rere)."
+            )
+    if transport_type == TRANSPORT_TYPE_REST:
+        if args.ssl_certfile and args.ssl_keyfile:
+            if not isfile(args.ssl_certfile):
+                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+            if not isfile(args.ssl_keyfile):
+                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
+            certificates = (
+                b"",
+                Path(args.ssl_certfile).read_bytes(),  # server certificate
+                Path(args.ssl_keyfile).read_bytes(),  # server private key
+            )
+            return certificates
+        if args.ssl_certfile or args.ssl_keyfile:
+            sys.exit(
+                "You need to provide valid file paths to `--ssl-certfile` "
+                "and `--ssl-keyfile` to create a secure connection "
+                "in Fleet API server (REST, experimental)."
+            )
+    log(
+        ERROR,
+        "Certificates are required unless running in insecure mode. "
+        "Please provide certificate paths to `--ssl-certfile`, "
+        "`--ssl-keyfile`, and `—-ssl-ca-certfile` or run the server "
+        "in insecure mode using '--insecure' if you understand the risks.",
+    )
+    sys.exit(1)

flwr/common/constant.py

@@ -38,17 +38,30 @@ TRANSPORT_TYPES = [
 ]
 
 # Addresses
+# Ports
+CLIENTAPPIO_PORT = "9094"
+SERVERAPPIO_PORT = "9091"
+FLEETAPI_GRPC_RERE_PORT = "9092"
+FLEETAPI_PORT = "9095"
+EXEC_API_PORT = "9093"
+SIMULATIONIO_PORT = "9096"
+# Octets
+SERVER_OCTET = "0.0.0.0"
+CLIENT_OCTET = "127.0.0.1"
 # SuperNode
-CLIENTAPPIO_API_DEFAULT_ADDRESS = "0.0.0.0:9094"
+CLIENTAPPIO_API_DEFAULT_SERVER_ADDRESS = f"{SERVER_OCTET}:{CLIENTAPPIO_PORT}"
+CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS = f"{CLIENT_OCTET}:{CLIENTAPPIO_PORT}"
 # SuperLink
-SERVERAPPIO_API_DEFAULT_ADDRESS = "0.0.0.0:9091"
-FLEET_API_GRPC_RERE_DEFAULT_ADDRESS = "0.0.0.0:9092"
+SERVERAPPIO_API_DEFAULT_SERVER_ADDRESS = f"{SERVER_OCTET}:{SERVERAPPIO_PORT}"
+SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS = f"{CLIENT_OCTET}:{SERVERAPPIO_PORT}"
+FLEET_API_GRPC_RERE_DEFAULT_ADDRESS = f"{SERVER_OCTET}:{FLEETAPI_GRPC_RERE_PORT}"
 FLEET_API_GRPC_BIDI_DEFAULT_ADDRESS = (
     "[::]:8080"  # IPv6 to keep start_server compatible
 )
-FLEET_API_REST_DEFAULT_ADDRESS = "0.0.0.0:9095"
-EXEC_API_DEFAULT_ADDRESS = "0.0.0.0:9093"
-SIMULATIONIO_API_DEFAULT_ADDRESS = "0.0.0.0:9096"
+FLEET_API_REST_DEFAULT_ADDRESS = f"{SERVER_OCTET}:{FLEETAPI_PORT}"
+EXEC_API_DEFAULT_SERVER_ADDRESS = f"{SERVER_OCTET}:{EXEC_API_PORT}"
+SIMULATIONIO_API_DEFAULT_SERVER_ADDRESS = f"{SERVER_OCTET}:{SIMULATIONIO_PORT}"
+SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS = f"{CLIENT_OCTET}:{SIMULATIONIO_PORT}"
 
 # Constants for ping
 PING_DEFAULT_INTERVAL = 30
@@ -94,6 +107,9 @@ CONN_RECONNECT_INTERVAL = 0.5  # Reconnect interval between two stream connectio
 LOG_STREAM_INTERVAL = 0.5  # Log stream interval for `ExecServicer.StreamLogs`
 LOG_UPLOAD_INTERVAL = 0.2  # Minimum interval between two log uploads
 
+# Retry configurations
+MAX_RETRY_DELAY = 20  # Maximum delay duration between two consecutive retries.
+
 
 class MessageType:
     """Message type."""
@@ -134,6 +150,8 @@ class ErrorCode:
     UNKNOWN = 0
     LOAD_CLIENT_APP_EXCEPTION = 1
     CLIENT_APP_RAISED_EXCEPTION = 2
+    MESSAGE_UNAVAILABLE = 3
+    REPLY_MESSAGE_UNAVAILABLE = 4
 
     def __new__(cls) -> ErrorCode:
         """Prevent instantiation."""

flwr/common/date.py

@@ -21,3 +21,21 @@ import datetime
 def now() -> datetime.datetime:
     """Construct a datetime from time.time() with time zone set to UTC."""
     return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
+def format_timedelta(td: datetime.timedelta) -> str:
+    """Format a timedelta as a string."""
+    days = td.days
+    hours, remainder = divmod(td.seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    if days > 0:
+        return f"{days}d {hours:02}:{minutes:02}:{seconds:02}"
+    return f"{hours:02}:{minutes:02}:{seconds:02}"
+
+
+def isoformat8601_utc(dt: datetime.datetime) -> str:
+    """Return the datetime formatted as an ISO 8601 string with a trailing 'Z'."""
+    if dt.tzinfo != datetime.timezone.utc:
+        raise ValueError("Expected datetime with timezone set to UTC")
+    return dt.isoformat(timespec="seconds").replace("+00:00", "Z")

flwr/common/grpc.py

@@ -53,7 +53,10 @@ def create_channel(
         channel = grpc.insecure_channel(server_address, options=channel_options)
         log(DEBUG, "Opened insecure gRPC connection (no certificates were passed)")
     else:
-        ssl_channel_credentials = grpc.ssl_channel_credentials(root_certificates)
+        try:
+            ssl_channel_credentials = grpc.ssl_channel_credentials(root_certificates)
+        except Exception as e:
+            raise ValueError(f"Failed to create SSL channel credentials: {e}") from e
         channel = grpc.secure_channel(
             server_address, ssl_channel_credentials, options=channel_options
         )

flwr/common/serde.py

@@ -872,6 +872,11 @@ def run_to_proto(run: typing.Run) -> ProtoRun:
         fab_version=run.fab_version,
         fab_hash=run.fab_hash,
         override_config=user_config_to_proto(run.override_config),
+        pending_at=run.pending_at,
+        starting_at=run.starting_at,
+        running_at=run.running_at,
+        finished_at=run.finished_at,
+        status=run_status_to_proto(run.status),
     )
     return proto
 
@@ -884,6 +889,11 @@ def run_from_proto(run_proto: ProtoRun) -> typing.Run:
         fab_version=run_proto.fab_version,
         fab_hash=run_proto.fab_hash,
         override_config=user_config_from_proto(run_proto.override_config),
+        pending_at=run_proto.pending_at,
+        starting_at=run_proto.starting_at,
+        running_at=run_proto.running_at,
+        finished_at=run_proto.finished_at,
+        status=run_status_from_proto(run_proto.status),
     )
     return run
 

flwr/common/typing.py

@@ -208,7 +208,16 @@ class ClientMessage:
 
 
 @dataclass
-class Run:
+class RunStatus:
+    """Run status information."""
+
+    status: str
+    sub_status: str
+    details: str
+
+
+@dataclass
+class Run:  # pylint: disable=too-many-instance-attributes
     """Run details."""
 
     run_id: int
@@ -216,15 +225,27 @@ class Run:
     fab_version: str
     fab_hash: str
     override_config: UserConfig
-
-
-@dataclass
-class RunStatus:
-    """Run status information."""
-
-    status: str
-    sub_status: str
-    details: str
+    pending_at: str
+    starting_at: str
+    running_at: str
+    finished_at: str
+    status: RunStatus
+
+    @classmethod
+    def create_empty(cls, run_id: int) -> "Run":
+        """Return an empty Run instance."""
+        return cls(
+            run_id=run_id,
+            fab_id="",
+            fab_version="",
+            fab_hash="",
+            override_config={},
+            pending_at="",
+            starting_at="",
+            running_at="",
+            finished_at="",
+            status=RunStatus(status="", sub_status="", details=""),
+        )
 
 
 @dataclass