common: add shared FLS binary download utilities

Add a shared module for FLS (Flasher) binary download utilities that can
be used by multiple drivers. Update flashers driver to use the shared
get_fls_github_url() function.

Signed-off-by: Benny Zlotnik <bzlotnik@redhat.com>
Assisted-by: claude-opus-4.5

Author: bennyz

python/packages/jumpstarter-driver-flashers/jumpstarter_driver_flashers/client.py

@@ -25,6 +25,7 @@
 
 from jumpstarter.client.decorators import driver_click_group
 from jumpstarter.common.exceptions import ArgumentError, JumpstarterException
+from jumpstarter.common.fls import get_fls_github_url
 
 
 class FlashError(JumpstarterException):
@@ -533,8 +534,8 @@ def _flash_with_fls(
             self._download_fls_binary(console, prompt, fls_binary_url, f"Failed to download FLS from {fls_binary_url}")
         elif fls_version != "":
             self.logger.info(f"Downloading FLS version {fls_version} from GitHub releases")
-            # Download fls binary to the target device (until it is available on the target device)
-            fls_url = f"https://github.com/jumpstarter-dev/fls/releases/download/{fls_version}/fls-aarch64-linux"
+            # Download fls binary to the target device (always aarch64 for target devices)
+            fls_url = get_fls_github_url(fls_version, arch="aarch64")
             self._download_fls_binary(console, prompt, fls_url, f"Failed to download FLS from {fls_url}")
 
         # Flash the image

python/packages/jumpstarter/jumpstarter/common/__init__.py

@@ -1,4 +1,13 @@
+from .fls import download_fls, get_fls_binary, get_fls_github_url
 from .metadata import Metadata
 from .tempfile import TemporarySocket, TemporaryTcpListener, TemporaryUnixListener
 
-__all__ = ["Metadata", "TemporarySocket", "TemporaryUnixListener", "TemporaryTcpListener"]
+__all__ = [
+    "Metadata",
+    "TemporarySocket",
+    "TemporaryUnixListener",
+    "TemporaryTcpListener",
+    "download_fls",
+    "get_fls_binary",
+    "get_fls_github_url",
+]

python/packages/jumpstarter/jumpstarter/common/fls.py

@@ -0,0 +1,93 @@
+"""FLS (Flasher) binary download utilities.
+
+This module provides functions for downloading the FLS binary tool
+used for flashing devices via fastboot with OCI image support.
+"""
+
+import logging
+import platform
+import tempfile
+import urllib.request
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+FLS_GITHUB_REPO = "jumpstarter-dev/fls"
+
+
+def get_fls_github_url(version: str, arch: str | None = None) -> str:
+    """Get GitHub release URL for FLS version.
+
+    Args:
+        version: FLS version (e.g., "0.1.9")
+        arch: Target architecture (e.g., "aarch64", "x86_64"). If None,
+              auto-detects from current platform.
+
+    Returns:
+        Download URL for the architecture-appropriate binary
+    """
+    if arch is None:
+        arch = platform.machine().lower()
+    else:
+        arch = arch.lower()
+    if arch in ("aarch64", "arm64"):
+        binary_name = "fls-aarch64-linux"
+    elif arch in ("x86_64", "amd64"):
+        binary_name = "fls-x86_64-linux"
+    else:
+        binary_name = "fls-aarch64-linux"  # Default to aarch64
+
+    return f"https://github.com/{FLS_GITHUB_REPO}/releases/download/{version}/{binary_name}"
+
+
+def download_fls(url: str) -> str:
+    """Download FLS binary from URL to a temp file.
+
+    Args:
+        url: URL to download FLS binary from
+
+    Returns:
+        Path to the downloaded binary
+    """
+    fd, binary_path = tempfile.mkstemp(prefix="fls-")
+    try:
+        logger.info(f"Downloading FLS binary from: {url}")
+        urllib.request.urlretrieve(url, binary_path)
+        Path(binary_path).chmod(0o755)
+        logger.info(f"FLS binary downloaded to: {binary_path}")
+        return binary_path
+    except Exception as e:
+        Path(binary_path).unlink(missing_ok=True)
+        logger.error(f"Failed to download FLS from {url}: {e}")
+        raise RuntimeError(f"Failed to download FLS from {url}: {e}") from e
+
+
+def get_fls_binary(
+    fls_version: str | None = None,
+    fls_binary_url: str | None = None,
+) -> str:
+    """Get path to FLS binary.
+
+    Priority order:
+    1. fls_binary_url - custom URL (highest priority)
+    2. fls_version - GitHub release version
+    3. System PATH - fallback to 'fls' command
+
+    Args:
+        fls_version: FLS version to download from GitHub releases
+        fls_binary_url: Custom URL to download FLS binary from
+
+    Returns:
+        Path to the FLS binary or 'fls' if using system PATH
+    """
+    if fls_binary_url:
+        logger.info(f"Using custom FLS binary URL: {fls_binary_url}")
+        return download_fls(fls_binary_url)
+
+    if fls_version:
+        github_url = get_fls_github_url(fls_version)
+        logger.info(f"Using FLS version {fls_version} from GitHub")
+        return download_fls(github_url)
+
+    logger.debug("Using FLS from system PATH")
+    return "fls"

python/packages/jumpstarter/jumpstarter/common/fls_test.py

@@ -0,0 +1,77 @@
+from unittest.mock import patch
+
+import pytest
+
+from .fls import download_fls, get_fls_binary, get_fls_github_url
+
+
+@pytest.mark.parametrize(
+    "arch,version,expected_binary",
+    [
+        ("aarch64", "0.1.9", "fls-aarch64-linux"),
+        ("arm64", "0.1.9", "fls-aarch64-linux"),
+        ("x86_64", "0.2.0", "fls-x86_64-linux"),
+        ("amd64", "0.2.0", "fls-x86_64-linux"),
+        ("unknown", "0.1.9", "fls-aarch64-linux"),  # defaults to aarch64
+    ],
+)
+def test_get_fls_github_url_auto_detect(arch, version, expected_binary):
+    """Test architecture auto-detection from platform.machine()"""
+    with patch("platform.machine", return_value=arch):
+        url = get_fls_github_url(version)
+        assert url == f"https://github.com/jumpstarter-dev/fls/releases/download/{version}/{expected_binary}"
+
+
+@pytest.mark.parametrize(
+    "arch,version,expected_binary",
+    [
+        ("aarch64", "0.1.9", "fls-aarch64-linux"),
+        ("AARCH64", "0.1.9", "fls-aarch64-linux"),  # case insensitive
+        ("x86_64", "0.2.0", "fls-x86_64-linux"),
+    ],
+)
+def test_get_fls_github_url_explicit_arch(arch, version, expected_binary):
+    """Test explicit architecture parameter (used by flashers for target device)"""
+    url = get_fls_github_url(version, arch=arch)
+    assert url == f"https://github.com/jumpstarter-dev/fls/releases/download/{version}/{expected_binary}"
+
+
+def test_get_fls_binary_with_custom_url():
+    with patch("jumpstarter.common.fls.download_fls", return_value="/tmp/custom-fls") as mock_download:
+        result = get_fls_binary(fls_binary_url="https://example.com/fls")
+
+        mock_download.assert_called_once_with("https://example.com/fls")
+        assert result == "/tmp/custom-fls"
+
+
+def test_get_fls_binary_with_version():
+    with patch("jumpstarter.common.fls.download_fls", return_value="/tmp/fls-0.1.9") as mock_download:
+        with patch("jumpstarter.common.fls.get_fls_github_url", return_value="https://github.com/...") as mock_url:
+            result = get_fls_binary(fls_version="0.1.9")
+
+            mock_url.assert_called_once_with("0.1.9")
+            mock_download.assert_called_once()
+            assert result == "/tmp/fls-0.1.9"
+
+
+def test_get_fls_binary_falls_back_to_path():
+    result = get_fls_binary()
+    assert result == "fls"
+
+
+def test_download_fls_success():
+    with patch("urllib.request.urlretrieve") as mock_retrieve:
+        with patch("tempfile.mkstemp", return_value=(0, "/tmp/fls-test")):
+            with patch("pathlib.Path.chmod"):
+                result = download_fls("https://example.com/fls")
+
+                mock_retrieve.assert_called_once_with("https://example.com/fls", "/tmp/fls-test")
+                assert result == "/tmp/fls-test"
+
+
+def test_download_fls_failure():
+    with patch("urllib.request.urlretrieve", side_effect=Exception("Network error")):
+        with patch("tempfile.mkstemp", return_value=(0, "/tmp/fls-test")):
+            with patch("pathlib.Path.unlink"):
+                with pytest.raises(RuntimeError, match="Failed to download FLS"):
+                    download_fls("https://example.com/fls")