flwr 1.24.0__py3-none-any.whl → 1.26.0__py3-none-any.whl

flwr/supercore/state/schema/linkstate_tables.py

@@ -0,0 +1,152 @@
+# Copyright 2026 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""SQLAlchemy Core Table definitions for LinkState."""
+
+
+from sqlalchemy import (
+    TIMESTAMP,
+    Column,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    LargeBinary,
+    MetaData,
+    String,
+    Table,
+    UniqueConstraint,
+)
+
+
+def create_linkstate_metadata() -> MetaData:
+    """Create and return MetaData with LinkState table definitions."""
+    metadata = MetaData()
+
+    # --------------------------------------------------------------------------
+    #  Table: node
+    # --------------------------------------------------------------------------
+    Table(
+        "node",
+        metadata,
+        Column("node_id", Integer, unique=True),
+        Column("owner_aid", String),
+        Column("owner_name", String),
+        Column("status", String),
+        Column("registered_at", String),
+        Column("last_activated_at", String, nullable=True),
+        Column("last_deactivated_at", String, nullable=True),
+        Column("unregistered_at", String, nullable=True),
+        Column("online_until", TIMESTAMP, nullable=True),
+        Column("heartbeat_interval", Float),
+        Column("public_key", LargeBinary, unique=True),
+        # Indexes
+        # Used in delete_node and get_node_info (security/filtering)
+        Index("idx_node_owner_aid", "owner_aid"),
+        # Used in get_nodes and activation checks (frequent filtering)
+        Index("idx_node_status", "status"),
+        # Used in heartbeat checks to efficiently find expired nodes
+        Index("idx_online_until", "online_until"),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: run
+    # --------------------------------------------------------------------------
+    Table(
+        "run",
+        metadata,
+        Column("run_id", Integer, unique=True),
+        Column("fab_id", String),
+        Column("fab_version", String),
+        Column("fab_hash", String),
+        Column("override_config", String),
+        Column("pending_at", String),
+        Column("starting_at", String),
+        Column("running_at", String),
+        Column("finished_at", String),
+        Column("sub_status", String),
+        Column("details", String),
+        Column("federation", String),
+        Column("federation_options", LargeBinary),
+        Column("flwr_aid", String),
+        Column("bytes_sent", Integer, server_default="0"),
+        Column("bytes_recv", Integer, server_default="0"),
+        Column("clientapp_runtime", Float, server_default="0.0"),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: logs
+    # --------------------------------------------------------------------------
+    Table(
+        "logs",
+        metadata,
+        Column("timestamp", Float),
+        Column("run_id", Integer, ForeignKey("run.run_id")),
+        Column("node_id", Integer),
+        Column("log", String),
+        # Composite PK
+        UniqueConstraint("timestamp", "run_id", "node_id"),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: context
+    # --------------------------------------------------------------------------
+    Table(
+        "context",
+        metadata,
+        Column("run_id", Integer, ForeignKey("run.run_id"), unique=True),
+        Column("context", LargeBinary),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: message_ins
+    # --------------------------------------------------------------------------
+    Table(
+        "message_ins",
+        metadata,
+        Column("message_id", String, unique=True),
+        Column("group_id", String),
+        Column("run_id", Integer, ForeignKey("run.run_id")),
+        Column("src_node_id", Integer),
+        Column("dst_node_id", Integer),
+        Column("reply_to_message_id", String),
+        Column("created_at", Float),
+        Column("delivered_at", String),
+        Column("ttl", Float),
+        Column("message_type", String),
+        Column("content", LargeBinary, nullable=True),
+        Column("error", LargeBinary, nullable=True),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: message_res
+    # --------------------------------------------------------------------------
+    Table(
+        "message_res",
+        metadata,
+        Column("message_id", String, unique=True),
+        Column("group_id", String),
+        Column("run_id", Integer, ForeignKey("run.run_id")),
+        Column("src_node_id", Integer),
+        Column("dst_node_id", Integer),
+        Column("reply_to_message_id", String),
+        Column("created_at", Float),
+        Column("delivered_at", String),
+        Column("ttl", Float),
+        Column("message_type", String),
+        Column("content", LargeBinary, nullable=True),
+        Column("error", LargeBinary, nullable=True),
+    )
+
+    return metadata

flwr/supercore/state/schema/objectstore_tables.py

@@ -0,0 +1,90 @@
+# Copyright 2026 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""SQLAlchemy Core Table definitions for ObjectStore."""
+
+
+from sqlalchemy import (
+    CheckConstraint,
+    Column,
+    ForeignKey,
+    Integer,
+    LargeBinary,
+    MetaData,
+    PrimaryKeyConstraint,
+    String,
+    Table,
+)
+
+
+def create_objectstore_metadata() -> MetaData:
+    """Create and return MetaData with ObjectStore table definitions."""
+    metadata = MetaData()
+
+    # --------------------------------------------------------------------------
+    #  Table: objects
+    # --------------------------------------------------------------------------
+    Table(
+        "objects",
+        metadata,
+        Column("object_id", String, primary_key=True, nullable=True),
+        Column("content", LargeBinary),
+        Column(
+            "is_available",
+            Integer,
+            nullable=False,
+            server_default="0",
+        ),
+        Column("ref_count", Integer, nullable=False, server_default="0"),
+        CheckConstraint("is_available IN (0, 1)", name="ck_objects_is_available"),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: object_children
+    # --------------------------------------------------------------------------
+    Table(
+        "object_children",
+        metadata,
+        Column(
+            "parent_id",
+            String,
+            ForeignKey("objects.object_id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        Column(
+            "child_id",
+            String,
+            ForeignKey("objects.object_id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        PrimaryKeyConstraint("parent_id", "child_id"),
+    )
+
+    # --------------------------------------------------------------------------
+    #  Table: run_objects
+    # --------------------------------------------------------------------------
+    Table(
+        "run_objects",
+        metadata,
+        Column("run_id", Integer, nullable=False),
+        Column(
+            "object_id",
+            String,
+            ForeignKey("objects.object_id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        PrimaryKeyConstraint("run_id", "object_id"),
+    )
+
+    return metadata

flwr/supercore/superexec/run_superexec.py

@@ -23,7 +23,7 @@ from flwr.common.config import get_flwr_dir
 from flwr.common.exit import ExitCode, flwr_exit, register_signal_handlers
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.logger import log
-from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
+from flwr.common.retry_invoker import make_simple_grpc_retry_invoker, wrap_stub
 from flwr.common.serde import run_from_proto
 from flwr.common.telemetry import EventType
 from flwr.common.typing import Run
@@ -101,7 +101,7 @@ def run_superexec(  # pylint: disable=R0913,R0914,R0917
 
     # Create the gRPC stub for the AppIO API
     stub = stub_class(channel)
-    _wrap_stub(stub, _make_simple_grpc_retry_invoker())
+    wrap_stub(stub, make_simple_grpc_retry_invoker())
 
     def get_run(run_id: int) -> Run:
         _req = GetRunRequest(run_id=run_id)

flwr/supercore/utils.py

@@ -15,6 +15,19 @@
 """Utility functions for the infrastructure."""
 
 
+import json
+import os
+import re
+from pathlib import Path
+
+import requests
+
+from flwr.common.constant import FLWR_DIR, FLWR_HOME
+from flwr.supercore.version import package_version as flwr_version
+
+from .constant import APP_ID_PATTERN, APP_VERSION_PATTERN
+
+
 def mask_string(value: str, head: int = 4, tail: int = 4) -> str:
     """Mask a string by preserving only the head and tail characters.
 
@@ -50,3 +63,215 @@ def int64_to_uint64(signed: int) -> int:
     if signed < 0:
         return signed + (1 << 64)
     return signed
+
+
+def get_flwr_home() -> Path:
+    """Get the Flower home directory path.
+
+    Returns FLWR_HOME environment variable if set, otherwise returns a default
+    subdirectory in the user's home directory.
+    """
+    if flwr_home := os.getenv(FLWR_HOME):
+        return Path(flwr_home)
+    return Path.home() / FLWR_DIR
+
+
+def parse_app_spec(app_spec: str) -> tuple[str, str | None]:
+    """Parse app specification string into app ID and version.
+
+    Parameters
+    ----------
+    app_spec : str
+        The app specification string in the format '@account/app' or
+        '@account/app==x.y.z' (digits only).
+
+    Returns
+    -------
+    tuple[str, str | None]
+        A tuple containing the app ID and optional version.
+
+    Raises
+    ------
+    ValueError
+        If the app specification format is invalid.
+    """
+    if "==" in app_spec:
+        app_id, app_version = app_spec.split("==", 1)
+
+        if not re.match(APP_VERSION_PATTERN, app_version):
+            raise ValueError(
+                "Invalid app version. Expected format: x.y.z (digits only)."
+            )
+    else:
+        app_id = app_spec
+        app_version = None
+
+    if not re.match(APP_ID_PATTERN, app_id):
+        raise ValueError(
+            "Invalid remote app ID. Expected format: '@account_name/app_name'."
+        )
+
+    return app_id, app_version
+
+
+def request_download_link(
+    app_id: str, app_version: str | None, in_url: str, out_url: str
+) -> tuple[str, list[dict[str, str]] | None]:
+    """Request a download link for the given app from the Flower Platform API.
+
+    Parameters
+    ----------
+    app_id : str
+        The application identifier in the format '@account/app'.
+    app_version : str | None
+        The application version (e.g., '1.2.3'), or None to request the latest version.
+    in_url : str
+        The Platform API endpoint URL to query.
+    out_url : str
+        The key name in the response that contains the download URL.
+
+    Returns
+    -------
+    tuple[str, list[dict[str, str]] | None]
+        A tuple containing:
+        - The download URL for the application.
+        - A list of verification dictionaries if provided by the API, otherwise None.
+
+    Raises
+    ------
+    ValueError
+        If the API connection fails, the application or version is not found,
+        the API returns a non-200 response, or the response format is invalid.
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    body = {
+        "app_id": app_id,  # send raw string of app_id
+        "app_version": app_version,
+        "flwr_version": flwr_version,
+    }
+
+    try:
+        resp = requests.post(in_url, headers=headers, data=json.dumps(body), timeout=20)
+    except requests.RequestException as e:
+        raise ValueError(f"Unable to connect to Platform API: {e}") from e
+
+    if resp.status_code == 404:
+        # Expecting a JSON body with a "detail" field
+        try:
+            error_message = resp.json().get("detail")
+        except ValueError:
+            # JSON parsing failed
+            raise ValueError(f"{app_id} not found in Platform API.") from None
+
+        if isinstance(error_message, dict):
+            available_app_versions = error_message.get("available_app_versions", [])
+            available_versions_str = (
+                ", ".join(map(str, available_app_versions))
+                if available_app_versions
+                else "None"
+            )
+            raise ValueError(
+                f"{app_id}=={app_version} not found in Platform API. "
+                f"Available app versions for {app_id}: {available_versions_str}"
+            )
+
+        raise ValueError(f"{app_id} not found in Platform API.")
+
+    if not resp.ok:
+        raise ValueError(
+            f"Platform API request failed with status {resp.status_code}. "
+            f"Details: {resp.text}"
+        )
+
+    data = resp.json()
+    if out_url not in data:
+        raise ValueError("Invalid response from Platform API")
+
+    verifications = data["verifications"] if "verifications" in data else None
+
+    return str(data[out_url]), verifications
+
+
+def humanize_duration(seconds: float) -> str:
+    """Convert a duration in seconds to a human-friendly string.
+
+    Rules:
+      - < 90 seconds: show seconds
+      - < 1 hour: show minutes + seconds
+      - < 1 day: show hours + minutes
+      - >= 1 day: show days + hours
+    """
+    seconds = int(seconds)
+
+    # Under 90 seconds → Seconds only
+    if seconds < 90:
+        return f"{seconds}s"
+
+    # Under 1 hour → Minutes and seconds
+    minutes, sec = divmod(seconds, 60)
+    if minutes < 60:
+        return f"{minutes}m {sec}s"
+
+    # Under 1 day → Hours and minutes
+    hours, minutes = divmod(minutes, 60)
+    if hours < 24:
+        return f"{hours}h {minutes}m"
+
+    # 1+ days → Days and hours
+    days, hours = divmod(hours, 24)
+    return f"{days}d {hours}h"
+
+
+def humanize_bytes(num_bytes: int) -> str:
+    """Convert a number of bytes to a human-friendly string.
+
+    Uses 1024-based units and 0-1 decimal precision.
+    Rules:
+      - < 1 KB: bytes
+      - < 1 MB: KB
+      - < 1 GB: MB
+      - < 1 TB: GB
+    """
+    value = float(num_bytes)
+
+    for suffix in ["B", "KB", "MB", "GB", "TB"]:
+        if value < 1024 or suffix == "TB":
+            # Bytes → no decimals
+            if suffix == "B":
+                return f"{int(value)} B"
+
+            # Decide precision: 1 decimal for <10, otherwise no decimal
+            if value < 10:
+                formatted = f"{value:.1f}"
+            else:
+                formatted = f"{int(value)}"
+
+            return f"{formatted} {suffix}"
+
+        value /= 1024
+
+    raise RuntimeError("Unreachable code")  # Make mypy happy
+
+
+def check_federation_format(federation: str) -> None:
+    """Check if the federation string is valid.
+
+    Parameters
+    ----------
+    federation : str
+        The federation string to check.
+
+    Raises
+    ------
+    ValueError
+        If the federation string is not valid. The expected
+        format is '@<account-name>/<federation-name>'.
+    """
+    if not re.match(r"^@[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+$", federation):
+        raise ValueError(
+            f"Invalid federation format: {federation}. "
+            f"Expected format: '@<account-name>/<federation-name>'."
+        )

flwr/superlink/federation/federation_manager.py

@@ -56,8 +56,8 @@ class FederationManager(ABC):
         """Given a node ID, check if it is in the federation."""
 
     @abstractmethod
-    def get_federations(self, flwr_aid: str) -> list[str]:
-        """Get federations of which the account is a member."""
+    def get_federations(self, flwr_aid: str) -> list[tuple[str, str]]:
+        """Get federations (name, description) of which the account is a member."""
 
     @abstractmethod
     def get_details(self, federation: str) -> Federation:

flwr/superlink/federation/noop_federation_manager.py

@@ -15,9 +15,10 @@
 """NoOp implementation of FederationManager."""
 
 
-from flwr.common.constant import NOOP_FLWR_AID
+from flwr.common.constant import NOOP_ACCOUNT_NAME, NOOP_FLWR_AID
 from flwr.common.typing import Federation
-from flwr.supercore.constant import NOOP_FEDERATION
+from flwr.proto.federation_pb2 import Account  # pylint: disable=E0611
+from flwr.supercore.constant import NOOP_FEDERATION, NOOP_FEDERATION_DESCRIPTION
 
 from .federation_manager import FederationManager
 
@@ -47,11 +48,11 @@ class NoOpFederationManager(FederationManager):
             raise ValueError(f"Federation '{federation}' does not exist.")
         return True
 
-    def get_federations(self, flwr_aid: str) -> list[str]:
-        """Get federations of which the account is a member."""
+    def get_federations(self, flwr_aid: str) -> list[tuple[str, str]]:
+        """Get federations (name, description) of which the account is a member."""
         if flwr_aid != NOOP_FLWR_AID:
             return []
-        return [NOOP_FEDERATION]
+        return [(NOOP_FEDERATION, NOOP_FEDERATION_DESCRIPTION)]
 
     def get_details(self, federation: str) -> Federation:
         """Get details of the federation."""
@@ -65,7 +66,8 @@ class NoOpFederationManager(FederationManager):
         ]
         return Federation(
             name=NOOP_FEDERATION,
-            member_aids=[NOOP_FLWR_AID],
+            description=NOOP_FEDERATION_DESCRIPTION,
+            accounts=[Account(id=NOOP_FLWR_AID, name=NOOP_ACCOUNT_NAME)],
             nodes=nodes,
             runs=runs,
         )

flwr/superlink/servicer/control/control_grpc.py

@@ -61,6 +61,7 @@ def run_control_api_grpc(
     authz_plugin: ControlAuthzPlugin,
     event_log_plugin: EventLogWriterPlugin | None = None,
     artifact_provider: ArtifactProvider | None = None,
+    fleet_api_type: str | None = None,
 ) -> grpc.Server:
     """Run Control API (gRPC, request-response)."""
     license_plugin: LicensePlugin | None = get_license_plugin()
@@ -74,6 +75,7 @@ def run_control_api_grpc(
         is_simulation=is_simulation,
         authn_plugin=authn_plugin,
         artifact_provider=artifact_provider,
+        fleet_api_type=fleet_api_type,
     )
     interceptors = [ControlAccountAuthInterceptor(authn_plugin, authz_plugin)]
     if license_plugin is not None: