flwr-nightly 1.19.0.dev20250511__py3-none-any.whl → 1.19.0.dev20250513__py3-none-any.whl

flwr/common/constant.py

@@ -62,6 +62,7 @@ HEARTBEAT_BASE_MULTIPLIER = 0.8
 HEARTBEAT_RANDOM_RANGE = (-0.1, 0.1)
 HEARTBEAT_MAX_INTERVAL = 1e300
 HEARTBEAT_PATIENCE = 2
+RUN_FAILURE_DETAILS_NO_HEARTBEAT = "No heartbeat received from the run."
 
 # IDs
 RUN_ID_NUM_BYTES = 8

flwr/common/heartbeat.py

@@ -77,6 +77,11 @@ class HeartbeatSender:
         self._stop_event.set()
         self._thread.join()
 
+    @property
+    def is_running(self) -> bool:
+        """Return True if the heartbeat sender is running, False otherwise."""
+        return self._thread.is_alive() and not self._stop_event.is_set()
+
     def _run(self) -> None:
         """Periodically send heartbeats until stopped."""
         while not self._stop_event.is_set():

flwr/common/inflatable.py

@@ -15,6 +15,8 @@
 """InflatableObject base class."""
 
 
+from __future__ import annotations
+
 import hashlib
 from typing import TypeVar
 
@@ -31,7 +33,9 @@ class InflatableObject:
         raise NotImplementedError()
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> "InflatableObject":
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> InflatableObject:
         """Inflate the object from bytes.
 
         Parameters
@@ -39,6 +43,10 @@ class InflatableObject:
         object_content : bytes
             The deflated object content.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Dictionary of children InflatableObjects mapped to their object IDs. These
+            childrens enable the full inflation of the parent InflatableObject.
+
         Returns
         -------
         InflatableObject
@@ -51,6 +59,11 @@ class InflatableObject:
         """Get object_id."""
         return get_object_id(self.deflate())
 
+    @property
+    def children(self) -> dict[str, InflatableObject] | None:
+        """Get all child objects as a dictionary or None if there are no children."""
+        return None
+
 
 def get_object_id(object_content: bytes) -> str:
     """Return a SHA-256 hash of the (deflated) object content."""

flwr/common/record/array.py

@@ -265,7 +265,9 @@ class Array(InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> Array:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> Array:
         """Inflate an Array from bytes.
 
         Parameters
@@ -273,11 +275,18 @@ class Array(InflatableObject):
         object_content : bytes
             The deflated object content of the Array.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``Array`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         Array
             The inflated Array.
         """
+        if children is not None:
+            raise ValueError("`Array` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         proto_array = ArrayProto.FromString(obj_body)
         return cls(

flwr/common/record/arrayrecord.py

@@ -18,6 +18,7 @@
 from __future__ import annotations
 
 import gc
+import json
 import sys
 from collections import OrderedDict
 from logging import WARN
@@ -26,6 +27,7 @@ from typing import TYPE_CHECKING, Any, cast, overload
 import numpy as np
 
 from ..constant import GC_THRESHOLD
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
 from ..typing import NDArray
 from .array import Array
@@ -56,7 +58,7 @@ def _check_value(value: Array) -> None:
         )
 
 
-class ArrayRecord(TypedDict[str, Array]):
+class ArrayRecord(TypedDict[str, Array], InflatableObject):
     """Array record.
 
     A typed dictionary (``str`` to :class:`Array`) that can store named arrays,
@@ -365,6 +367,68 @@ class ArrayRecord(TypedDict[str, Array]):
 
         return num_bytes
 
+    @property
+    def children(self) -> dict[str, InflatableObject]:
+        """Return a dictionary of Arrays with their Object IDs as keys."""
+        return {arr.object_id: arr for arr in self.values()}
+
+    def deflate(self) -> bytes:
+        """Deflate the ArrayRecord."""
+        # array_name: array_object_id mapping
+        array_refs: dict[str, str] = {}
+
+        for array_name, array in self.items():
+            array_refs[array_name] = array.object_id
+
+        # Serialize references dict
+        object_body = json.dumps(array_refs).encode("utf-8")
+        return add_header_to_object_body(object_body=object_body, cls=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> ArrayRecord:
+        """Inflate an ArrayRecord from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the ArrayRecord.
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the ArrayRecord.
+
+        Returns
+        -------
+        ArrayRecord
+            The inflated ArrayRecord.
+        """
+        if children is None:
+            children = {}
+
+        # Inflate mapping of array_names (keys in the ArrayRecord) to Arrays' object IDs
+        obj_body = get_object_body(object_content, cls)
+        array_refs: dict[str, str] = json.loads(obj_body.decode(encoding="utf-8"))
+
+        unique_arrays = set(array_refs.values())
+        children_obj_ids = set(children.keys())
+        if unique_arrays != children_obj_ids:
+            raise ValueError(
+                "Unexpected set of `children`. "
+                f"Expected {unique_arrays} but got {children_obj_ids}."
+            )
+
+        # Ensure children are of type Array
+        if not all(isinstance(arr, Array) for arr in children.values()):
+            raise ValueError("`Children` are expected to be of type `Array`.")
+
+        # Instantiate new ArrayRecord
+        return ArrayRecord(
+            OrderedDict(
+                {name: children[object_id] for name, object_id in array_refs.items()}
+            )
+        )
+
 
 class ParametersRecord(ArrayRecord):
     """Deprecated class ``ParametersRecord``, use ``ArrayRecord`` instead.

flwr/common/record/configrecord.py

@@ -185,7 +185,9 @@ class ConfigRecord(TypedDict[str, ConfigRecordValues], InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> ConfigRecord:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> ConfigRecord:
         """Inflate a ConfigRecord from bytes.
 
         Parameters
@@ -193,11 +195,18 @@ class ConfigRecord(TypedDict[str, ConfigRecordValues], InflatableObject):
         object_content : bytes
             The deflated object content of the ConfigRecord.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``ConfigRecord`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         ConfigRecord
             The inflated ConfigRecord.
         """
+        if children is not None:
+            raise ValueError("`ConfigRecord` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         config_record_proto = ProtoConfigRecord.FromString(obj_body)
 

flwr/common/record/metricrecord.py

@@ -160,7 +160,9 @@ class MetricRecord(TypedDict[str, MetricRecordValues], InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> MetricRecord:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> MetricRecord:
         """Inflate a MetricRecord from bytes.
 
         Parameters
@@ -168,11 +170,18 @@ class MetricRecord(TypedDict[str, MetricRecordValues], InflatableObject):
         object_content : bytes
             The deflated object content of the MetricRecord.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``MetricRecord`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         MetricRecord
             The inflated MetricRecord.
         """
+        if children is not None:
+            raise ValueError("`MetricRecord` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         metric_record_proto = ProtoMetricRecord.FromString(obj_body)
 

flwr/common/record/recorddict.py

@@ -17,10 +17,12 @@
 
 from __future__ import annotations
 
+import json
 from logging import WARN
 from textwrap import indent
 from typing import TypeVar, Union, cast
 
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
 from .arrayrecord import ArrayRecord
 from .configrecord import ConfigRecord
@@ -97,7 +99,7 @@ class _SyncedDict(TypedDict[str, T]):
             )
 
 
-class RecordDict(TypedDict[str, RecordType]):
+class RecordDict(TypedDict[str, RecordType], InflatableObject):
     """RecordDict stores groups of arrays, metrics and configs.
 
     A :class:`RecordDict` is the unified mechanism by which arrays,
@@ -286,6 +288,72 @@ class RecordDict(TypedDict[str, RecordType]):
             )
         return self.config_records
 
+    @property
+    def children(self) -> dict[str, InflatableObject]:
+        """Return a dictionary of records with their Object IDs as keys."""
+        return {record.object_id: record for record in self.values()}
+
+    def deflate(self) -> bytes:
+        """Deflate the RecordDict."""
+        # record_name: record_object_id mapping
+        record_refs: dict[str, str] = {}
+
+        for record_name, record in self.items():
+            record_refs[record_name] = record.object_id
+
+        # Serialize references dict
+        object_body = json.dumps(record_refs).encode("utf-8")
+        return add_header_to_object_body(object_body=object_body, cls=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> RecordDict:
+        """Inflate an RecordDict from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the RecordDict.
+        children : Optional[dict[str, InflatableObject]]  (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the RecordDict. Default is None.
+
+        Returns
+        -------
+        RecordDict
+            The inflated RecordDict.
+        """
+        if children is None:
+            children = {}
+
+        # Inflate mapping of record_names (keys in the RecordDict) to Record' object IDs
+        obj_body = get_object_body(object_content, cls)
+        record_refs: dict[str, str] = json.loads(obj_body.decode(encoding="utf-8"))
+
+        unique_records = set(record_refs.values())
+        children_obj_ids = set(children.keys())
+        if unique_records != children_obj_ids:
+            raise ValueError(
+                "Unexpected set of `children`. "
+                f"Expected {unique_records} but got {children_obj_ids}."
+            )
+
+        # Ensure children are one of the *Record objects exepecte in a RecordDict
+        if not all(
+            isinstance(ch, (ArrayRecord, ConfigRecord, MetricRecord))
+            for ch in children.values()
+        ):
+            raise ValueError(
+                "`Children` are expected to be of type `ArrayRecord`, "
+                "`ConfigRecord` or `MetricRecord`."
+            )
+
+        # Instantiate new RecordDict
+        return RecordDict(
+            {name: children[object_id] for name, object_id in record_refs.items()}  # type: ignore
+        )
+
 
 class RecordSet(RecordDict):
     """Deprecated class ``RecordSet``, use ``RecordDict`` instead.

flwr/server/superlink/linkstate/in_memory_linkstate.py

@@ -25,12 +25,15 @@ from uuid import UUID, uuid4
 
 from flwr.common import Context, Message, log, now
 from flwr.common.constant import (
+    HEARTBEAT_MAX_INTERVAL,
     HEARTBEAT_PATIENCE,
     MESSAGE_TTL_TOLERANCE,
     NODE_ID_NUM_BYTES,
+    RUN_FAILURE_DETAILS_NO_HEARTBEAT,
     RUN_ID_NUM_BYTES,
     SUPERLINK_NODE_ID,
     Status,
+    SubStatus,
 )
 from flwr.common.record import ConfigRecord
 from flwr.common.typing import Run, RunStatus, UserConfig
@@ -52,8 +55,11 @@ class RunRecord:  # pylint: disable=R0902
     """The record of a specific run, including its status and timestamps."""
 
     run: Run
+    active_until: float = 0.0
+    heartbeat_interval: float = 0.0
     logs: list[tuple[float, str]] = field(default_factory=list)
     log_lock: threading.Lock = field(default_factory=threading.Lock)
+    lock: threading.RLock = field(default_factory=threading.RLock)
 
 
 class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
@@ -461,8 +467,29 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
         with self.lock:
             return set(self.run_ids.keys())
 
+    def _check_and_tag_inactive_run(self, run_ids: set[int]) -> None:
+        """Check if any runs are no longer active.
+
+        Marks runs with status 'starting' or 'running' as failed
+        if they have not sent a heartbeat before `active_until`.
+        """
+        current = now()
+        for record in [self.run_ids[run_id] for run_id in run_ids]:
+            with record.lock:
+                if record.run.status.status in (Status.STARTING, Status.RUNNING):
+                    if record.active_until < current.timestamp():
+                        record.run.status = RunStatus(
+                            status=Status.FINISHED,
+                            sub_status=SubStatus.FAILED,
+                            details=RUN_FAILURE_DETAILS_NO_HEARTBEAT,
+                        )
+                        record.run.finished_at = now().isoformat()
+
     def get_run(self, run_id: int) -> Optional[Run]:
         """Retrieve information about the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         with self.lock:
             if run_id not in self.run_ids:
                 log(ERROR, "`run_id` is invalid")
@@ -471,6 +498,9 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
 
     def get_run_status(self, run_ids: set[int]) -> dict[int, RunStatus]:
         """Retrieve the statuses for the specified runs."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids=run_ids)
+
         with self.lock:
             return {
                 run_id: self.run_ids[run_id].run.status
@@ -480,12 +510,16 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
 
     def update_run_status(self, run_id: int, new_status: RunStatus) -> bool:
         """Update the status of the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         with self.lock:
             # Check if the run_id exists
             if run_id not in self.run_ids:
                 log(ERROR, "`run_id` is invalid")
                 return False
 
+        with self.run_ids[run_id].lock:
             # Check if the status transition is valid
             current_status = self.run_ids[run_id].run.status
             if not is_valid_transition(current_status, new_status):
@@ -507,14 +541,23 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
                 )
                 return False
 
-            # Update the status
+            # Initialize heartbeat_interval and active_until
+            # when switching to starting or running
+            current = now()
             run_record = self.run_ids[run_id]
+            if new_status.status in (Status.STARTING, Status.RUNNING):
+                run_record.heartbeat_interval = HEARTBEAT_MAX_INTERVAL
+                run_record.active_until = (
+                    current.timestamp() + run_record.heartbeat_interval
+                )
+
+            # Update the run status
             if new_status.status == Status.STARTING:
-                run_record.run.starting_at = now().isoformat()
+                run_record.run.starting_at = current.isoformat()
             elif new_status.status == Status.RUNNING:
-                run_record.run.running_at = now().isoformat()
+                run_record.run.running_at = current.isoformat()
             elif new_status.status == Status.FINISHED:
-                run_record.run.finished_at = now().isoformat()
+                run_record.run.finished_at = current.isoformat()
             run_record.run.status = new_status
             return True
 
@@ -558,6 +601,43 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
                 return True
         return False
 
+    def acknowledge_app_heartbeat(self, run_id: int, heartbeat_interval: float) -> bool:
+        """Acknowledge a heartbeat received from a ServerApp for a given run.
+
+        A run with status `"running"` is considered alive as long as it sends heartbeats
+        within the tolerated interval: HEARTBEAT_PATIENCE × heartbeat_interval.
+        HEARTBEAT_PATIENCE = N allows for N-1 missed heartbeat before the run is
+        marked as `"completed:failed"`.
+        """
+        with self.lock:
+            # Search for the run
+            record = self.run_ids.get(run_id)
+
+            # Check if the run_id exists
+            if record is None:
+                log(ERROR, "`run_id` is invalid")
+                return False
+
+        with record.lock:
+            # Check if runs are still active
+            self._check_and_tag_inactive_run(run_ids={run_id})
+
+            # Check if the run is of status "running"/"starting"
+            current_status = record.run.status
+            if current_status.status not in (Status.RUNNING, Status.STARTING):
+                log(
+                    ERROR,
+                    'Cannot acknowledge heartbeat for run with status "%s"',
+                    current_status.status,
+                )
+                return False
+
+            # Update the `active_until` and `heartbeat_interval` for the given run
+            current = now().timestamp()
+            record.active_until = current + HEARTBEAT_PATIENCE * heartbeat_interval
+            record.heartbeat_interval = heartbeat_interval
+            return True
+
     def get_serverapp_context(self, run_id: int) -> Optional[Context]:
         """Get the context for the specified `run_id`."""
         return self.contexts.get(run_id)

flwr/server/superlink/linkstate/linkstate.py

@@ -292,6 +292,29 @@ class LinkState(abc.ABC):  # pylint: disable=R0904
             True if the heartbeat is successfully acknowledged; otherwise, False.
         """
 
+    @abc.abstractmethod
+    def acknowledge_app_heartbeat(self, run_id: int, heartbeat_interval: float) -> bool:
+        """Acknowledge a heartbeat received from a ServerApp for a given run.
+
+        A run with status `"running"` is considered alive as long as it sends heartbeats
+        within the tolerated interval: HEARTBEAT_PATIENCE × heartbeat_interval.
+        HEARTBEAT_PATIENCE = N allows for N-1 missed heartbeat before the run is
+        marked as `"completed:failed"`.
+
+        Parameters
+        ----------
+        run_id : int
+            The `run_id` from which the heartbeat was received.
+        heartbeat_interval : float
+            The interval (in seconds) from the current timestamp within which the next
+            heartbeat from the ServerApp for this run must be received.
+
+        Returns
+        -------
+        is_acknowledged : bool
+            True if the heartbeat is successfully acknowledged; otherwise, False.
+        """
+
     @abc.abstractmethod
     def get_serverapp_context(self, run_id: int) -> Optional[Context]:
         """Get the context for the specified `run_id`.

flwr/server/superlink/linkstate/sqlite_linkstate.py

@@ -28,12 +28,15 @@ from uuid import UUID, uuid4
 
 from flwr.common import Context, Message, Metadata, log, now
 from flwr.common.constant import (
+    HEARTBEAT_MAX_INTERVAL,
     HEARTBEAT_PATIENCE,
     MESSAGE_TTL_TOLERANCE,
     NODE_ID_NUM_BYTES,
+    RUN_FAILURE_DETAILS_NO_HEARTBEAT,
     RUN_ID_NUM_BYTES,
     SUPERLINK_NODE_ID,
     Status,
+    SubStatus,
 )
 from flwr.common.message import make_message
 from flwr.common.record import ConfigRecord
@@ -92,6 +95,8 @@ CREATE INDEX IF NOT EXISTS idx_online_until ON node (online_until);
 SQL_CREATE_TABLE_RUN = """
 CREATE TABLE IF NOT EXISTS run(
     run_id                INTEGER UNIQUE,
+    active_until          REAL,
+    heartbeat_interval    REAL,
     fab_id                TEXT,
     fab_version           TEXT,
     fab_hash              TEXT,
@@ -742,20 +747,21 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
         if self.query(query, (sint64_run_id,))[0]["COUNT(*)"] == 0:
             query = (
                 "INSERT INTO run "
-                "(run_id, fab_id, fab_version, fab_hash, override_config, "
-                "federation_options, pending_at, starting_at, running_at, finished_at, "
-                "sub_status, details) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);"
+                "(run_id, active_until, heartbeat_interval, fab_id, fab_version, "
+                "fab_hash, override_config, federation_options, pending_at, "
+                "starting_at, running_at, finished_at, sub_status, details) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);"
             )
             override_config_json = json.dumps(override_config)
             data = [
                 sint64_run_id,
+                0,  # The `active_until` is not used until the run is started
+                0,  # This `heartbeat_interval` is not used until the run is started
                 fab_id,
                 fab_version,
                 fab_hash,
                 override_config_json,
                 configrecord_to_bytes(federation_options),
-            ]
-            data += [
                 now().isoformat(),
                 "",
                 "",
@@ -796,8 +802,33 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
         rows = self.query(query)
         return {convert_sint64_to_uint64(row["run_id"]) for row in rows}
 
+    def _check_and_tag_inactive_run(self, run_ids: set[int]) -> None:
+        """Check if any runs are no longer active.
+
+        Marks runs with status 'starting' or 'running' as failed
+        if they have not sent a heartbeat before `active_until`.
+        """
+        sint_run_ids = [convert_uint64_to_sint64(run_id) for run_id in run_ids]
+        query = "UPDATE run SET finished_at = ?, sub_status = ?, details = ? "
+        query += "WHERE starting_at != '' AND finished_at = '' AND active_until < ?"
+        query += f" AND run_id IN ({','.join(['?'] * len(run_ids))});"
+        current = now()
+        self.query(
+            query,
+            (
+                current.isoformat(),
+                SubStatus.FAILED,
+                RUN_FAILURE_DETAILS_NO_HEARTBEAT,
+                current.timestamp(),
+                *sint_run_ids,
+            ),
+        )
+
     def get_run(self, run_id: int) -> Optional[Run]:
         """Retrieve information about the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         # Convert the uint64 value to sint64 for SQLite
         sint64_run_id = convert_uint64_to_sint64(run_id)
         query = "SELECT * FROM run WHERE run_id = ?;"
@@ -825,6 +856,9 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
 
     def get_run_status(self, run_ids: set[int]) -> dict[int, RunStatus]:
         """Retrieve the statuses for the specified runs."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids=run_ids)
+
         # Convert the uint64 value to sint64 for SQLite
         sint64_run_ids = (convert_uint64_to_sint64(run_id) for run_id in set(run_ids))
         query = f"SELECT * FROM run WHERE run_id IN ({','.join(['?'] * len(run_ids))});"
@@ -842,6 +876,9 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
 
     def update_run_status(self, run_id: int, new_status: RunStatus) -> bool:
         """Update the status of the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         # Convert the uint64 value to sint64 for SQLite
         sint64_run_id = convert_uint64_to_sint64(run_id)
         query = "SELECT * FROM run WHERE run_id = ?;"
@@ -879,9 +916,22 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
             return False
 
         # Update the status
-        query = "UPDATE run SET %s= ?, sub_status = ?, details = ? "
+        query = "UPDATE run SET %s= ?, sub_status = ?, details = ?, "
+        query += "active_until = ?, heartbeat_interval = ? "
         query += "WHERE run_id = ?;"
 
+        # Prepare data for query
+        # Initialize heartbeat_interval and active_until
+        # when switching to starting or running
+        current = now()
+        if new_status.status in (Status.STARTING, Status.RUNNING):
+            heartbeat_interval = HEARTBEAT_MAX_INTERVAL
+            active_until = current.timestamp() + heartbeat_interval
+        else:
+            heartbeat_interval = 0
+            active_until = 0
+
+        # Determine the timestamp field based on the new status
         timestamp_fld = ""
         if new_status.status == Status.STARTING:
             timestamp_fld = "starting_at"
@@ -891,10 +941,12 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
             timestamp_fld = "finished_at"
 
         data = (
-            now().isoformat(),
+            current.isoformat(),
             new_status.sub_status,
             new_status.details,
-            sint64_run_id,
+            active_until,
+            heartbeat_interval,
+            convert_uint64_to_sint64(run_id),
         )
         self.query(query % timestamp_fld, data)
         return True
@@ -957,6 +1009,44 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
         )
         return True
 
+    def acknowledge_app_heartbeat(self, run_id: int, heartbeat_interval: float) -> bool:
+        """Acknowledge a heartbeat received from a ServerApp for a given run.
+
+        A run with status `"running"` is considered alive as long as it sends heartbeats
+        within the tolerated interval: HEARTBEAT_PATIENCE × heartbeat_interval.
+        HEARTBEAT_PATIENCE = N allows for N-1 missed heartbeat before the run is
+        marked as `"completed:failed"`.
+        """
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
+        # Search for the run
+        sint_run_id = convert_uint64_to_sint64(run_id)
+        query = "SELECT * FROM run WHERE run_id = ?;"
+        rows = self.query(query, (sint_run_id,))
+
+        if not rows:
+            log(ERROR, "`run_id` is invalid")
+            return False
+
+        # Check if the run is of status "running"/"starting"
+        row = rows[0]
+        status = determine_run_status(row)
+        if status not in (Status.RUNNING, Status.STARTING):
+            log(
+                ERROR,
+                'Cannot acknowledge heartbeat for run with status "%s"',
+                status,
+            )
+            return False
+
+        # Update the `active_until` and `heartbeat_interval` for the given run
+        active_until = now().timestamp() + HEARTBEAT_PATIENCE * heartbeat_interval
+        query = "UPDATE run SET active_until = ?, heartbeat_interval = ? "
+        query += "WHERE run_id = ?"
+        self.query(query, (active_until, heartbeat_interval, sint_run_id))
+        return True
+
     def get_serverapp_context(self, run_id: int) -> Optional[Context]:
         """Get the context for the specified `run_id`."""
         # Retrieve context if any

{flwr_nightly-1.19.0.dev20250511.dist-info → flwr_nightly-1.19.0.dev20250513.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.19.0.dev20250511
+Version: 1.19.0.dev20250513
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

{flwr_nightly-1.19.0.dev20250511.dist-info → flwr_nightly-1.19.0.dev20250513.dist-info}/RECORD

@@ -115,7 +115,7 @@ flwr/common/args.py,sha256=-aX_jVnSaDrJR2KZ8Wq0Y3dQHII4R4MJtJOIXzVUA0c,5417
 flwr/common/auth_plugin/__init__.py,sha256=m271m9YjK2QfKDOuIIhcTvGmv1GWh1PL97QB05NTSHs,887
 flwr/common/auth_plugin/auth_plugin.py,sha256=GaXw4IiU2DkVNkp5S9ue821sbkU9zWSu6HSVZetEdjs,3938
 flwr/common/config.py,sha256=glcZDjco-amw1YfQcYTFJ4S1pt9APoexT-mf1QscuHs,13960
-flwr/common/constant.py,sha256=RmVW2YLGosdBzyePgj2EMdZnHrT1PKEtNScaNK_FHZ0,7302
+flwr/common/constant.py,sha256=Q8N-up1TvL_vllV_QA8mQlKjqVJ6Kdoze3iem6nSF9E,7375
 flwr/common/context.py,sha256=Be8obQR_OvEDy1OmshuUKxGRQ7Qx89mf5F4xlhkR10s,2407
 flwr/common/date.py,sha256=1ZT2cRSpC2DJqprOVTLXYCR_O2_OZR0zXO_brJ3LqWc,1554
 flwr/common/differential_privacy.py,sha256=FdlpdpPl_H_2HJa8CQM1iCUGBBQ5Dc8CzxmHERM-EoE,6148
@@ -128,20 +128,20 @@ flwr/common/exit/exit.py,sha256=mJgbqMlVlwAgYtq-Vedj53wO4VxcDcy_P-GzqGK-1GQ,3452
 flwr/common/exit/exit_code.py,sha256=PNEnCrZfOILjfDAFu5m-2YWEJBrk97xglq4zCUlqV7E,3470
 flwr/common/exit_handlers.py,sha256=MEk5_savTLphn-6lW57UQlos-XrFA39XEBn-OF1vXXg,3174
 flwr/common/grpc.py,sha256=manTaHaPiyYngUq1ErZvvV2B2GxlXUUUGRy3jc3TBIQ,9798
-flwr/common/heartbeat.py,sha256=yzi-gWH5wswdg0hfQwxwGkjI5twxIHBBVW45MD5QITI,3924
-flwr/common/inflatable.py,sha256=yCfnRYj4xeUqV2m-K5hcQPeVhL7gdSGw7CewPYKnjnE,3156
+flwr/common/heartbeat.py,sha256=nU0SNlL0A6t736ku7D7z7UUB1vXaX9QIn2fsJJPWeBU,4125
+flwr/common/inflatable.py,sha256=o3PQejN8GNm_xlHKJLB1h2wQzOXKkDfaiy6z5o142pA,3681
 flwr/common/logger.py,sha256=JbRf6E2vQxXzpDBq1T8IDUJo_usu3gjWEBPQ6uKcmdg,13049
 flwr/common/message.py,sha256=znr205Erq2hkxwFbvNNCsQTRS2UKv_Qsyu0sFNEhEAw,23721
 flwr/common/object_ref.py,sha256=p3SfTeqo3Aj16SkB-vsnNn01zswOPdGNBitcbRnqmUk,9134
 flwr/common/parameter.py,sha256=UVw6sOgehEFhFs4uUCMl2kfVq1PD6ncmWgPLMsZPKPE,2095
 flwr/common/pyproject.py,sha256=2SU6yJW7059SbMXgzjOdK1GZRWO6AixDH7BmdxbMvHI,1386
 flwr/common/record/__init__.py,sha256=cNGccdDoxttqgnUgyKRIqLWULjW-NaSmOufVxtXq-sw,1197
-flwr/common/record/array.py,sha256=tPTT6cw7B1Fo626LOVaA_sfj2_EtkxdnvSkRTyPrVRY,10469
-flwr/common/record/arrayrecord.py,sha256=KbehV2yXJ_6ZWcHPPrC-MNkE00DRCObxgyrVLwBQ5OY,14389
-flwr/common/record/configrecord.py,sha256=lXVGjNfQD3lqvQTstGPFfQjeEHl29alfoL9trCKKlY4,9269
+flwr/common/record/array.py,sha256=7c5peTvVsnhXQVvYOIFqm2UowGO-Uu0_44EeqybU0HY,10850
+flwr/common/record/arrayrecord.py,sha256=-9iIfBKtCS-fGmh5NLTDS7GTHqfHA3o1MguPyyybAyI,16787
+flwr/common/record/configrecord.py,sha256=2BqauemtQBsZDWLtkTZp51_4J7L9-8i5LrM9RV8nmNQ,9664
 flwr/common/record/conversion_utils.py,sha256=wbNCzy7oAqaA3-arhls_EqRZYXRC4YrWIoE-Gy82fJ0,1191
-flwr/common/record/metricrecord.py,sha256=MRMv0fSmJvHlg0HtX_s4IBqxHAh8QHgFN75CmR6fBOU,8444
-flwr/common/record/recorddict.py,sha256=zo7TiVZCH_LB9gwUP7-Jo-jLpFLrvxYSryovwZANQiw,12386
+flwr/common/record/metricrecord.py,sha256=PGeYISykqf_NSyij-qXdf85Pfnder7Rw9CagIolBe30,8839
+flwr/common/record/recorddict.py,sha256=qnRET_r6_7o7JSQQO2PnMAKezA4yZEy0frsfy8CKxb8,14986
 flwr/common/record/typeddict.py,sha256=dDKgUThs2BscYUNcgP82KP8-qfAYXYftDrf2LszAC_o,3599
 flwr/common/recorddict_compat.py,sha256=Znn1xRGiqLpPPgviVqyb-GPTM-pCK6tpnEmhWSXafy8,14119
 flwr/common/retry_invoker.py,sha256=T6puUH3nCxdRzQHeanyr-0nTxhRiS1TH07rmef9vuLQ,14482
@@ -293,10 +293,10 @@ flwr/server/superlink/fleet/vce/backend/backend.py,sha256=-wDHjgAy5mrfEgXj0GxkJI
 flwr/server/superlink/fleet/vce/backend/raybackend.py,sha256=Hx9hxL7lju1_VJoAwkhBOGerZ3628u0P1zgkPhGWRPY,7154
 flwr/server/superlink/fleet/vce/vce_api.py,sha256=m7WUiHRl-jTqzjH3cqNCj3RXe3ohT6V6I0JIR6zWZj8,12780
 flwr/server/superlink/linkstate/__init__.py,sha256=OtsgvDTnZLU3k0sUbkHbqoVwW6ql2FDmb6uT6DbNkZo,1064
-flwr/server/superlink/linkstate/in_memory_linkstate.py,sha256=vu36ntb9N1qeDWvt6YsnPfvVppZPJi04icAgolui9no,22520
-flwr/server/superlink/linkstate/linkstate.py,sha256=zrVR9UpeuCfgqK5MDIqudcXtFjvsCRjD2ylv4UZu8MU,12140
+flwr/server/superlink/linkstate/in_memory_linkstate.py,sha256=vvoOWjYlmOlbakH7AzpMh0jB70Qxx7UTlAGqjcA8ctM,25926
+flwr/server/superlink/linkstate/linkstate.py,sha256=j6nW351t07VrBhFqjO34z8tf2PuKOE9aCX9SqpW96pQ,13100
 flwr/server/superlink/linkstate/linkstate_factory.py,sha256=8RlosqSpKOoD_vhUUQPY0jtE3A84GeF96Z7sWNkRRcA,2069
-flwr/server/superlink/linkstate/sqlite_linkstate.py,sha256=c-6iopBJ3Y09Jh0qYka02tdIUF3Aq9X0nrBK5eAuwOk,39847
+flwr/server/superlink/linkstate/sqlite_linkstate.py,sha256=E43YO88vdnG9GW6Rwh9Fb7oWGgEABS9RXDRg3OR3T4Q,43573
 flwr/server/superlink/linkstate/utils.py,sha256=AJs9jTAEK7JnjF2AODXnOfy0pKAKpe6oUWPCanAP57s,15382
 flwr/server/superlink/serverappio/__init__.py,sha256=Fy4zJuoccZe5mZSEIpOmQvU6YeXFBa1M4eZuXXmJcn8,717
 flwr/server/superlink/serverappio/serverappio_grpc.py,sha256=opJ6SYwIAbu4NWEo3K-VxFO-tMSFmE4H3i2HwHIVRzw,2173
@@ -333,7 +333,7 @@ flwr/superexec/exec_servicer.py,sha256=Z0YYfs6eNPhqn8rY0x_R04XgR2mKFpggt07IH0EhU
 flwr/superexec/exec_user_auth_interceptor.py,sha256=iqygALkOMBUu_s_R9G0mFThZA7HTUzuXCLgxLCefiwI,4440
 flwr/superexec/executor.py,sha256=M5ucqSE53jfRtuCNf59WFLqQvA1Mln4741TySeZE7qQ,3112
 flwr/superexec/simulation.py,sha256=j6YwUvBN7EQ09ID7MYOCVZ70PGbuyBy8f9bXU0EszEM,4088
-flwr_nightly-1.19.0.dev20250511.dist-info/METADATA,sha256=NL5XgF9L-oJRThfCtBe-l84Z_6WJkNNNhPghf3SMFQg,15910
-flwr_nightly-1.19.0.dev20250511.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-flwr_nightly-1.19.0.dev20250511.dist-info/entry_points.txt,sha256=2-1L-GNKhwGw2_7_RoH55vHw2SIHjdAQy3HAVAWl9PY,374
-flwr_nightly-1.19.0.dev20250511.dist-info/RECORD,,
+flwr_nightly-1.19.0.dev20250513.dist-info/METADATA,sha256=4dlTZbixbfPDUcDbK3OBZ3JwaIFV553qWtAcY4d6zpQ,15910
+flwr_nightly-1.19.0.dev20250513.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+flwr_nightly-1.19.0.dev20250513.dist-info/entry_points.txt,sha256=2-1L-GNKhwGw2_7_RoH55vHw2SIHjdAQy3HAVAWl9PY,374
+flwr_nightly-1.19.0.dev20250513.dist-info/RECORD,,