flwr-nightly 1.23.0.dev20251030__py3-none-any.whl → 1.23.0.dev20251031__py3-none-any.whl

flwr/cli/new/new.py

@@ -15,14 +15,20 @@
 """Flower command line interface `new` command."""
 
 
+import io
+import json
 import re
+import zipfile
 from enum import Enum
 from pathlib import Path
 from string import Template
 from typing import Annotated, Optional
 
+import requests
 import typer
 
+from flwr.supercore.constant import APP_ID_PATTERN, PLATFORM_API_URL
+
 from ..utils import (
     is_valid_project_name,
     prompt_options,
@@ -93,6 +99,180 @@ def render_and_create(file_path: Path, template: str, context: dict[str, str]) -
     create_file(file_path, content)
 
 
+def print_success_prompt(
+    package_name: str, llm_challenge_str: Optional[str] = None
+) -> None:
+    """Print styled setup instructions for running a new Flower App after creation."""
+    prompt = typer.style(
+        "🎊 Flower App creation successful.\n\n"
+        "To run your Flower App, first install its dependencies:\n\n",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    _add = "	huggingface-cli login\n" if llm_challenge_str else ""
+
+    prompt += typer.style(
+        f"	cd {package_name} && pip install -e .\n" + _add + "\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "then, run the app:\n\n ",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "\tflwr run .\n\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "💡 Check the README in your app directory to learn how to\n"
+        "customize it and how to run it using the Deployment Runtime.\n",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    print(prompt)
+
+
+# Security: prevent zip-slip
+def _safe_extract_zip(zf: zipfile.ZipFile, dest_dir: Path) -> None:
+    """Extract ZIP file into destination directory."""
+    dest_dir = dest_dir.resolve()
+
+    def _is_within_directory(base: Path, target: Path) -> bool:
+        try:
+            target.relative_to(base)
+            return True
+        except ValueError:
+            return False
+
+    for member in zf.infolist():
+        # Skip directory placeholders;
+        # ZipInfo can represent them as names ending with '/'.
+        if member.is_dir():
+            target_path = (dest_dir / member.filename).resolve()
+            if not _is_within_directory(dest_dir, target_path):
+                raise ValueError(f"Unsafe path in zip: {member.filename}")
+            target_path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        # Files
+        target_path = (dest_dir / member.filename).resolve()
+        if not _is_within_directory(dest_dir, target_path):
+            raise ValueError(f"Unsafe path in zip: {member.filename}")
+
+        # Ensure parent exists
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Extract
+        with zf.open(member, "r") as src, open(target_path, "wb") as dst:
+            dst.write(src.read())
+
+
+def _download_zip_to_memory(presigned_url: str) -> io.BytesIO:
+    """Download ZIP file from Platform API to memory."""
+    try:
+        r = requests.get(presigned_url, timeout=60)
+        r.raise_for_status()
+    except requests.RequestException as e:
+        raise typer.BadParameter(f"ZIP download failed: {e}") from e
+
+    buf = io.BytesIO(r.content)
+    # Validate it's a zip
+    if not zipfile.is_zipfile(buf):
+        raise typer.BadParameter("Downloaded file is not a valid ZIP")
+    buf.seek(0)
+    return buf
+
+
+def _request_download_link(identifier: str) -> str:
+    """Request download link from Flower platform API."""
+    url = f"{PLATFORM_API_URL}/hub/fetch-zip"
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    body = {
+        "identifier": identifier,  # send raw string of identifier
+    }
+
+    try:
+        resp = requests.post(url, headers=headers, data=json.dumps(body), timeout=20)
+    except requests.RequestException as e:
+        raise typer.BadParameter(f"Unable to connect to Platform API: {e}") from e
+
+    if resp.status_code == 404:
+        raise typer.BadParameter(f"'{identifier}' not found in Platform API")
+    if not resp.ok:
+        raise typer.BadParameter(
+            f"Platform API request failed with "
+            f"status {resp.status_code}. Details: {resp.text}"
+        )
+
+    data = resp.json()
+    if "zip_url" not in data:
+        raise typer.BadParameter("Invalid response from Platform API")
+    return str(data["zip_url"])
+
+
+def download_remote_app_via_api(identifier: str) -> None:
+    """Download App from Platform API."""
+    # Parse @user/app just to derive local dir name
+    m = re.match(APP_ID_PATTERN, identifier)
+    if not m:
+        raise typer.BadParameter(
+            "Invalid remote app ID. Expected format: '@user_name/app_name'."
+        )
+    app_name = m.group("app")
+
+    project_dir = Path.cwd() / app_name
+    if project_dir.exists():
+        if not typer.confirm(
+            typer.style(
+                f"\n💬 {app_name} already exists, do you want to override it?",
+                fg=typer.colors.MAGENTA,
+                bold=True,
+            )
+        ):
+            return
+
+    print(
+        typer.style(
+            f"\n🔗 Requesting download link for {identifier}...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    presigned_url = _request_download_link(identifier)
+
+    print(
+        typer.style(
+            "⬇️  Downloading ZIP into memory...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    zip_buf = _download_zip_to_memory(presigned_url)
+
+    print(
+        typer.style(
+            f"📦 Unpacking into {project_dir}...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    with zipfile.ZipFile(zip_buf) as zf:
+        _safe_extract_zip(zf, Path.cwd())
+
+    print_success_prompt(app_name)
+
+
 # pylint: disable=too-many-locals,too-many-branches,too-many-statements
 def new(
     app_name: Annotated[
@@ -111,6 +291,12 @@ def new(
     """Create new Flower App."""
     if app_name is None:
         app_name = prompt_text("Please provide the app name")
+
+    # Download remote app
+    if app_name and app_name.startswith("@"):
+        download_remote_app_via_api(app_name)
+        return
+
     if not is_valid_project_name(app_name):
         app_name = prompt_text(
             "Please provide a name that only contains "
@@ -282,38 +468,4 @@ def new(
             context=context,
         )
 
-    prompt = typer.style(
-        "🎊 Flower App creation successful.\n\n"
-        "To run your Flower App, first install its dependencies:\n\n",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    _add = "	huggingface-cli login\n" if llm_challenge_str else ""
-
-    prompt += typer.style(
-        f"	cd {package_name} && pip install -e .\n" + _add + "\n",
-        fg=typer.colors.BRIGHT_CYAN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "then, run the app:\n\n ",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "\tflwr run .\n\n",
-        fg=typer.colors.BRIGHT_CYAN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "💡 Check the README in your app directory to learn how to\n"
-        "customize it and how to run it using the Deployment Runtime.\n",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    print(prompt)
+    print_success_prompt(package_name, llm_challenge_str)

flwr/client/grpc_adapter_client/connection.py

@@ -44,10 +44,9 @@ def grpc_adapter(  # pylint: disable=R0913,too-many-positional-arguments
     ] = None,
 ) -> Iterator[
     tuple[
+        int,
         Callable[[], Optional[tuple[Message, ObjectTree]]],
         Callable[[Message, ObjectTree], set[str]],
-        Callable[[], Optional[int]],
-        Callable[[], None],
         Callable[[int], Run],
         Callable[[str, int], Fab],
         Callable[[int, str], bytes],
@@ -81,12 +80,11 @@ def grpc_adapter(  # pylint: disable=R0913,too-many-positional-arguments
 
     Returns
     -------
+    node_id : int
     receive : Callable[[], Optional[tuple[Message, ObjectTree]]]
     send : Callable[[Message, ObjectTree], set[str]]
-    create_node : Optional[Callable]
-    delete_node : Optional[Callable]
-    get_run : Optional[Callable]
-    get_fab : Optional[Callable]
+    get_run : Callable[[int], Run]
+    get_fab : Callable[[str, int], Fab]
     pull_object : Callable[[str], bytes]
     push_object : Callable[[str, bytes], None]
     confirm_message_received : Callable[[str], None]

flwr/client/grpc_rere_client/connection.py

@@ -19,7 +19,7 @@ from collections.abc import Iterator, Sequence
 from contextlib import contextmanager
 from logging import ERROR
 from pathlib import Path
-from typing import Callable, Optional, Union, cast
+from typing import Callable, Optional, Union
 
 import grpc
 from cryptography.hazmat.primitives.asymmetric import ec
@@ -45,12 +45,15 @@ from flwr.common.serde import (
 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
-    CreateNodeRequest,
-    DeleteNodeRequest,
+    ActivateNodeRequest,
+    ActivateNodeResponse,
+    DeactivateNodeRequest,
     PullMessagesRequest,
     PullMessagesResponse,
     PushMessagesRequest,
     PushMessagesResponse,
+    RegisterNodeFleetRequest,
+    UnregisterNodeFleetRequest,
 )
 from flwr.proto.fleet_pb2_grpc import FleetStub  # pylint: disable=E0611
 from flwr.proto.heartbeat_pb2 import (  # pylint: disable=E0611
@@ -79,10 +82,9 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     adapter_cls: Optional[Union[type[FleetStub], type[GrpcAdapter]]] = None,
 ) -> Iterator[
     tuple[
+        int,
         Callable[[], Optional[tuple[Message, ObjectTree]]],
         Callable[[Message, ObjectTree], set[str]],
-        Callable[[], Optional[int]],
-        Callable[[], None],
         Callable[[int], Run],
         Callable[[str, int], Fab],
         Callable[[int, str], bytes],
@@ -125,11 +127,11 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
     Returns
     -------
-    receive : Callable
-    send : Callable
-    create_node : Optional[Callable]
-    delete_node : Optional[Callable]
-    get_run : Optional[Callable]
+    node_id : int
+    receive : Callable[[], Optional[tuple[Message, ObjectTree]]]
+    send : Callable[[Message, ObjectTree], set[str]]
+    get_run : Callable[[int], Run]
+    get_fab : Callable[[str, int], Fab]
     pull_object : Callable[[str], bytes]
     push_object : Callable[[str, bytes], None]
     confirm_message_received : Callable[[str], None]
@@ -138,7 +140,9 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         root_certificates = Path(root_certificates).read_bytes()
 
     # Automatic node auth: generate keys if user didn't provide any
+    self_registered = False
     if authentication_keys is None:
+        self_registered = True
         authentication_keys = generate_key_pairs()
 
     # Always configure auth interceptor, with either user-provided or generated keys
@@ -164,7 +168,7 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     # Wrap stub
     _wrap_stub(stub, retry_invoker)
     ###########################################################################
-    # send_node_heartbeat/create_node/delete_node/receive/send/get_run functions
+    # SuperNode functions
     ###########################################################################
 
     def send_node_heartbeat() -> bool:
@@ -201,23 +205,26 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
     heartbeat_sender = HeartbeatSender(send_node_heartbeat)
 
-    def create_node() -> Optional[int]:
-        """Set create_node."""
-        # Call FleetAPI
-        create_node_request = CreateNodeRequest(
+    def register_node() -> None:
+        """Register node with SuperLink."""
+        stub.RegisterNode(RegisterNodeFleetRequest(public_key=node_pk))
+
+    def activate_node() -> int:
+        """Activate node and start heartbeat."""
+        req = ActivateNodeRequest(
             public_key=node_pk,
             heartbeat_interval=HEARTBEAT_DEFAULT_INTERVAL,
         )
-        create_node_response = stub.CreateNode(request=create_node_request)
+        res: ActivateNodeResponse = stub.ActivateNode(req)
 
         # Remember the node and start the heartbeat sender
         nonlocal node
-        node = cast(Node, create_node_response.node)
+        node = Node(node_id=res.node_id)
         heartbeat_sender.start()
         return node.node_id
 
-    def delete_node() -> None:
-        """Set delete_node."""
+    def deactivate_node() -> None:
+        """Deactivate node and stop heartbeat."""
         # Get Node
         nonlocal node
         if node is None:
@@ -228,8 +235,20 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         heartbeat_sender.stop()
 
         # Call FleetAPI
-        delete_node_request = DeleteNodeRequest(node=node)
-        stub.DeleteNode(request=delete_node_request)
+        req = DeactivateNodeRequest(node_id=node.node_id)
+        stub.DeactivateNode(req)
+
+    def unregister_node() -> None:
+        """Unregister node from SuperLink."""
+        # Get Node
+        nonlocal node
+        if node is None:
+            log(ERROR, "Node instance missing")
+            return
+
+        # Call FleetAPI
+        req = UnregisterNodeFleetRequest(node_id=node.node_id)
+        stub.UnregisterNode(req)
 
         # Cleanup
         node = None
@@ -336,12 +355,14 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         fn(object_id)
 
     try:
+        if self_registered:
+            register_node()
+        node_id = activate_node()
         # Yield methods
         yield (
+            node_id,
             receive,
             send,
-            create_node,
-            delete_node,
             get_run,
             get_fab,
             pull_object,
@@ -356,7 +377,9 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
             if node is not None:
                 # Disable retrying
                 retry_invoker.max_tries = 1
-                delete_node()
+                deactivate_node()
+                if self_registered:
+                    unregister_node()
         except grpc.RpcError:
             pass
         channel.close()

flwr/client/grpc_rere_client/grpc_adapter.py

@@ -36,12 +36,8 @@ from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     ActivateNodeRequest,
     ActivateNodeResponse,
-    CreateNodeRequest,
-    CreateNodeResponse,
     DeactivateNodeRequest,
     DeactivateNodeResponse,
-    DeleteNodeRequest,
-    DeleteNodeResponse,
     PullMessagesRequest,
     PullMessagesResponse,
     PushMessagesRequest,
@@ -126,18 +122,6 @@ class GrpcAdapter:
         response.ParseFromString(container_res.grpc_message_content)
         return response
 
-    def CreateNode(  # pylint: disable=C0103
-        self, request: CreateNodeRequest, **kwargs: Any
-    ) -> CreateNodeResponse:
-        """."""
-        return self._send_and_receive(request, CreateNodeResponse, **kwargs)
-
-    def DeleteNode(  # pylint: disable=C0103
-        self, request: DeleteNodeRequest, **kwargs: Any
-    ) -> DeleteNodeResponse:
-        """."""
-        return self._send_and_receive(request, DeleteNodeResponse, **kwargs)
-
     def RegisterNode(  # pylint: disable=C0103
         self, request: RegisterNodeFleetRequest, **kwargs: Any
     ) -> RegisterNodeFleetResponse:

flwr/client/rest_client/connection.py

@@ -15,7 +15,6 @@
 """Contextmanager for a REST request-response channel to the Flower server."""
 
 
-import secrets
 from collections.abc import Iterator
 from contextlib import contextmanager
 from logging import ERROR, WARN
@@ -46,14 +45,18 @@ from flwr.common.serde import (
 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
-    CreateNodeRequest,
-    CreateNodeResponse,
-    DeleteNodeRequest,
-    DeleteNodeResponse,
+    ActivateNodeRequest,
+    ActivateNodeResponse,
+    DeactivateNodeRequest,
+    DeactivateNodeResponse,
     PullMessagesRequest,
     PullMessagesResponse,
     PushMessagesRequest,
     PushMessagesResponse,
+    RegisterNodeFleetRequest,
+    RegisterNodeFleetResponse,
+    UnregisterNodeFleetRequest,
+    UnregisterNodeFleetResponse,
 )
 from flwr.proto.heartbeat_pb2 import (  # pylint: disable=E0611
     SendNodeHeartbeatRequest,
@@ -70,6 +73,7 @@ from flwr.proto.message_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
 from flwr.proto.run_pb2 import GetRunRequest, GetRunResponse  # pylint: disable=E0611
+from flwr.supercore.primitives.asymmetric import generate_key_pairs, public_key_to_bytes
 
 try:
     import requests
@@ -77,8 +81,10 @@ except ModuleNotFoundError:
     flwr_exit(ExitCode.COMMON_MISSING_EXTRA_REST)
 
 
-PATH_CREATE_NODE: str = "api/v0/fleet/create-node"
-PATH_DELETE_NODE: str = "api/v0/fleet/delete-node"
+PATH_REGISTER_NODE: str = "/api/v0/fleet/register-node"
+PATH_ACTIVATE_NODE: str = "/api/v0/fleet/activate-node"
+PATH_DEACTIVATE_NODE: str = "/api/v0/fleet/deactivate-node"
+PATH_UNREGISTER_NODE: str = "/api/v0/fleet/unregister-node"
 PATH_PULL_MESSAGES: str = "/api/v0/fleet/pull-messages"
 PATH_PUSH_MESSAGES: str = "/api/v0/fleet/push-messages"
 PATH_PULL_OBJECT: str = "/api/v0/fleet/pull-object"
@@ -105,10 +111,9 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     ] = None,
 ) -> Iterator[
     tuple[
+        int,
         Callable[[], Optional[tuple[Message, ObjectTree]]],
         Callable[[Message, ObjectTree], set[str]],
-        Callable[[], Optional[int]],
-        Callable[[], None],
         Callable[[int], Run],
         Callable[[str, int], Fab],
         Callable[[int, str], bytes],
@@ -144,11 +149,11 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
     Returns
     -------
-    receive : Callable
-    send : Callable
-    create_node : Optional[Callable]
-    delete_node : Optional[Callable]
-    get_run : Optional[Callable]
+    node_id : int
+    receive : Callable[[], Optional[tuple[Message, ObjectTree]]]
+    send : Callable[[Message, ObjectTree], set[str]]
+    get_run : Callable[[int], Run]
+    get_fab : Callable[[str, int], Fab]
     pull_object : Callable[[str], bytes]
     push_object : Callable[[str, bytes], None]
     confirm_message_received : Callable[[str], None]
@@ -179,6 +184,13 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     if authentication_keys is not None:
         log(ERROR, "Client authentication is not supported for this transport type.")
 
+    # REST does NOT support node authentication
+    self_registered = False
+    if authentication_keys is None:
+        self_registered = True
+        authentication_keys = generate_key_pairs()
+    node_pk = public_key_to_bytes(authentication_keys[1])
+
     # Shared variables for inner functions
     node: Optional[Node] = None
 
@@ -186,7 +198,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     retry_invoker.should_giveup = None
 
     ###########################################################################
-    # heartbeat/create_node/delete_node/receive/send/get_run functions
+    # SuperNode functions
     ###########################################################################
 
     def _request(
@@ -296,28 +308,35 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
     heartbeat_sender = HeartbeatSender(send_node_heartbeat)
 
-    def create_node() -> Optional[int]:
-        """Set create_node."""
-        req = CreateNodeRequest(
-            # REST does not support node authentication;
-            # random bytes are used instead
-            public_key=secrets.token_bytes(32),
+    def register_node() -> None:
+        """Register node with SuperLink."""
+        req = RegisterNodeFleetRequest(public_key=node_pk)
+
+        # Send the request
+        res = _request(req, RegisterNodeFleetResponse, PATH_REGISTER_NODE)
+        if res is None:
+            raise RuntimeError("Failed to register node")
+
+    def activate_node() -> int:
+        """Activate node and start heartbeat."""
+        req = ActivateNodeRequest(
+            public_key=node_pk,
             heartbeat_interval=HEARTBEAT_DEFAULT_INTERVAL,
         )
 
         # Send the request
-        res = _request(req, CreateNodeResponse, PATH_CREATE_NODE)
+        res = _request(req, ActivateNodeResponse, PATH_ACTIVATE_NODE)
         if res is None:
-            return None
+            raise RuntimeError("Failed to activate node")
 
         # Remember the node and start the heartbeat sender
         nonlocal node
-        node = res.node
+        node = Node(node_id=res.node_id)
         heartbeat_sender.start()
         return node.node_id
 
-    def delete_node() -> None:
-        """Set delete_node."""
+    def deactivate_node() -> None:
+        """Deactivate node and stop heartbeat."""
         nonlocal node
         if node is None:
             raise RuntimeError("Node instance missing")
@@ -325,13 +344,27 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         # Stop the heartbeat sender
         heartbeat_sender.stop()
 
-        # Send DeleteNode request
-        req = DeleteNodeRequest(node=node)
+        # Send DeactivateNode request
+        req = DeactivateNodeRequest(node_id=node.node_id)
+
+        # Send the request
+        res = _request(req, DeactivateNodeResponse, PATH_DEACTIVATE_NODE)
+        if res is None:
+            raise RuntimeError("Failed to deactivate node")
+
+    def unregister_node() -> None:
+        """Unregister node from SuperLink."""
+        nonlocal node
+        if node is None:
+            raise RuntimeError("Node instance missing")
+
+        # Send UnregisterNode request
+        req = UnregisterNodeFleetRequest(node_id=node.node_id)
 
         # Send the request
-        res = _request(req, DeleteNodeResponse, PATH_DELETE_NODE)
+        res = _request(req, UnregisterNodeFleetResponse, PATH_UNREGISTER_NODE)
         if res is None:
-            return
+            raise RuntimeError("Failed to unregister node")
 
         # Cleanup
         node = None
@@ -447,12 +480,14 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         fn(object_id)
 
     try:
+        if self_registered:
+            register_node()
+        node_id = activate_node()
         # Yield methods
         yield (
+            node_id,
             receive,
             send,
-            create_node,
-            delete_node,
             get_run,
             get_fab,
             pull_object,
@@ -467,6 +502,8 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
             if node is not None:
                 # Disable retrying
                 retry_invoker.max_tries = 1
-                delete_node()
+                deactivate_node()
+                if self_registered:
+                    unregister_node()
         except RequestsConnectionError:
             pass