napt 0.3.1__py3-none-any.whl

napt/discovery/api_json.py

@@ -0,0 +1,452 @@
+# Copyright 2025 Roger Cibrian
+#
+# 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.
+
+"""JSON API discovery strategy for NAPT.
+
+This is a VERSION-FIRST strategy that queries JSON API endpoints to get version
+and download URL WITHOUT downloading the installer. This enables fast version
+checks and efficient caching.
+
+Key Advantages:
+
+- Fast version discovery (API call ~100ms)
+- Can skip downloads entirely when version unchanged
+- Direct API access for version and download URL
+- Support for complex JSON structures with JSONPath
+- Custom headers for authentication
+- Support for GET and POST requests
+- No file parsing required
+- Ideal for CI/CD with scheduled checks
+
+Supported Features:
+
+- JSONPath navigation for nested structures
+- Array indexing and filtering
+- Custom HTTP headers (Authorization, etc.)
+- POST requests with JSON body
+- Environment variable expansion in values
+
+Use Cases:
+
+- Vendors with JSON APIs (Microsoft, Mozilla, etc.)
+- Cloud services with version endpoints
+- CDNs that provide metadata APIs
+- Applications with update check APIs
+- APIs requiring authentication or custom headers
+- CI/CD pipelines with frequent version checks
+
+Recipe Configuration:
+    ```yaml
+    source:
+        strategy: api_json
+        api_url: "https://vendor.com/api/latest"
+        version_path: "version"                      # JSONPath to version
+        download_url_path: "download_url"            # JSONPath to URL
+        method: "GET"                                # Optional: GET or POST
+        headers:                                     # Optional: custom headers
+        Authorization: "Bearer ${API_TOKEN}"
+        Accept: "application/json"
+        body:                                        # Optional: POST body
+        platform: "windows"
+        arch: "x64"
+        timeout: 30                                  # Optional: timeout in seconds
+    ```
+
+Configuration Fields:
+
+- **api_url** (str, required): API endpoint URL that returns JSON with version
+    and download information
+- **version_path** (str, required): JSONPath expression to extract version from
+    the API response. Examples: "version", "release.version", "data.version"
+- **download_url_path** (str, required): JSONPath expression to extract
+    download URL from the API response. Examples: "download_url", "assets.url",
+    "platforms.windows.x64"
+- **method** (str, optional): HTTP method to use. Either "GET" or "POST".
+    Default is "GET"
+- **headers** (dict, optional): Custom HTTP headers to send with the request.
+    Useful for authentication or setting Accept headers. Values support
+    environment variable expansion. Example: {"Authorization": "Bearer ${API_TOKEN}"}
+- **body** (dict, optional): Request body for POST requests. Sent as JSON.
+    Only used when method="POST". Example: {"platform": "windows", "arch": "x64"}
+    - **timeout** (int, optional): Request timeout in seconds. Default is 30.
+
+JSONPath Syntax:
+
+- Simple paths: "version", "release.version"
+- Array indexing: "data.version", "releases.version"
+- Nested paths: "data.latest.download.url", "response.assets.browser_download_url"
+
+Error Handling:
+
+- ValueError: Missing or invalid configuration, invalid JSONPath, path not found
+- RuntimeError: API failures, invalid JSON response
+- Errors are chained with 'from err' for better debugging
+
+Example:
+    In a recipe YAML (simple API):
+        ```yaml
+        apps:
+          - name: "My App"
+            id: "my-app"
+            source:
+              strategy: api_json
+              api_url: "https://api.vendor.com/latest"
+              version_path: "version"
+              download_url_path: "download_url"
+        ```
+
+    In a recipe YAML (nested structure):
+        ```yaml
+        apps:
+          - name: "My App"
+            id: "my-app"
+            source:
+              strategy: api_json
+              api_url: "https://api.vendor.com/releases"
+              version_path: "stable.version"
+              download_url_path: "stable.platforms.windows.x64"
+              headers:
+                Authorization: "Bearer ${API_TOKEN}"
+        ```
+
+    From Python (version-first approach):
+        ```python
+        from napt.discovery.api_json import ApiJsonStrategy
+        from napt.io import download_file
+
+        strategy = ApiJsonStrategy()
+        app_config = {
+            "source": {
+                "api_url": "https://api.vendor.com/latest",
+                "version_path": "version",
+                "download_url_path": "download_url",
+            }
+        }
+
+        # Get version WITHOUT downloading
+        version_info = strategy.get_version_info(app_config)
+        print(f"Latest version: {version_info.version}")
+
+        # Download only if needed
+        if need_to_download:
+            file_path, sha256, headers = download_file(
+                version_info.download_url, Path("./downloads")
+            )
+            print(f"Downloaded to {file_path}")
+        ```
+
+    From Python (using core orchestration):
+        ```python
+        from pathlib import Path
+        from napt.core import discover_recipe
+
+        # Automatically uses version-first optimization
+        result = discover_recipe(Path("recipe.yaml"), Path("./downloads"))
+        print(f"Version {result.version} at {result.file_path}")
+        ```
+
+Note:
+    - Version discovery via API only (no download required)
+    - Core orchestration automatically skips download if version unchanged
+    - JSONPath uses jsonpath-ng library for robust parsing
+    - Environment variable expansion works in headers and other string values
+    - POST body is sent as JSON (Content-Type: application/json)
+    - Timeout defaults to 30 seconds to prevent hanging on slow APIs
+
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from jsonpath_ng import parse as jsonpath_parse
+import requests
+
+from napt.exceptions import ConfigError, NetworkError
+from napt.versioning.keys import VersionInfo
+
+from .base import register_strategy
+
+
+class ApiJsonStrategy:
+    """Discovery strategy for JSON API endpoints.
+
+    Configuration example:
+        source:
+          strategy: api_json
+          api_url: "https://api.vendor.com/latest"
+          version_path: "version"
+          download_url_path: "download_url"
+          method: "GET"
+          headers:
+            Authorization: "Bearer ${API_TOKEN}"
+    """
+
+    def get_version_info(
+        self,
+        app_config: dict[str, Any],
+    ) -> VersionInfo:
+        """Query JSON API for version and download URL without downloading
+        (version-first path).
+
+        This method calls a JSON API, extracts version and download URL using
+        JSONPath expressions. If the version matches cached state, the download
+        can be skipped entirely.
+
+        Args:
+            app_config: App configuration containing source.api_url,
+                source.version_path, and source.download_url_path.
+
+        Returns:
+            Version info with version string, download URL, and
+                source name.
+
+        Raises:
+            ValueError: If required config fields are missing, invalid, or if
+                JSONPath expressions don't match anything in the response.
+            RuntimeError: If API call fails (chained with 'from err').
+
+        Example:
+            Get version info from JSON API:
+                ```python
+                strategy = ApiJsonStrategy()
+                config = {
+                    "source": {
+                        "api_url": "https://api.vendor.com/latest",
+                        "version_path": "version",
+                        "download_url_path": "download_url"
+                    }
+                }
+                version_info = strategy.get_version_info(config)
+                # version_info.version returns: '1.0.0'
+                ```
+
+        """
+        from napt.logging import get_global_logger
+
+        logger = get_global_logger()
+        # Validate configuration
+        source = app_config.get("source", {})
+        api_url = source.get("api_url")
+        if not api_url:
+            raise ConfigError("api_json strategy requires 'source.api_url' in config")
+
+        version_path = source.get("version_path")
+        if not version_path:
+            raise ConfigError(
+                "api_json strategy requires 'source.version_path' in config"
+            )
+
+        download_url_path = source.get("download_url_path")
+        if not download_url_path:
+            raise ConfigError(
+                "api_json strategy requires 'source.download_url_path' in config"
+            )
+
+        # Optional configuration
+        method = source.get("method", "GET").upper()
+        if method not in ("GET", "POST"):
+            raise ConfigError(f"Invalid method: {method!r}. Must be 'GET' or 'POST'")
+
+        headers = source.get("headers", {})
+        body = source.get("body", {})
+        timeout = source.get("timeout", 30)
+
+        logger.verbose("DISCOVERY", "Strategy: api_json (version-first)")
+        logger.verbose("DISCOVERY", f"API URL: {api_url}")
+        logger.verbose("DISCOVERY", f"Method: {method}")
+        logger.verbose("DISCOVERY", f"Version path: {version_path}")
+        logger.verbose("DISCOVERY", f"Download URL path: {download_url_path}")
+
+        # Expand environment variables in headers
+        expanded_headers = {}
+        for key, value in headers.items():
+            if (
+                isinstance(value, str)
+                and value.startswith("${")
+                and value.endswith("}")
+            ):
+                env_var = value[2:-1]
+                env_value = os.environ.get(env_var)
+                if not env_value:
+                    logger.verbose(
+                        "DISCOVERY",
+                        f"Warning: Environment variable {env_var} not set",
+                    )
+                else:
+                    expanded_headers[key] = env_value
+            else:
+                expanded_headers[key] = value
+
+        # Make API request
+        logger.verbose("DISCOVERY", f"Calling API: {method} {api_url}")
+        try:
+            if method == "GET":
+                response = requests.get(
+                    api_url, headers=expanded_headers, timeout=timeout
+                )
+            else:  # POST
+                response = requests.post(
+                    api_url,
+                    headers=expanded_headers,
+                    json=body,
+                    timeout=timeout,
+                )
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as err:
+            raise NetworkError(
+                f"API request failed: {response.status_code} {response.reason}"
+            ) from err
+        except requests.exceptions.RequestException as err:
+            raise NetworkError(f"Failed to call API: {err}") from err
+
+        logger.verbose("DISCOVERY", f"API response: {response.status_code} OK")
+
+        # Parse JSON response
+        try:
+            json_data = response.json()
+        except json.JSONDecodeError as err:
+            raise NetworkError(
+                f"Invalid JSON response from API. Response: {response.text[:200]}"
+            ) from err
+
+        logger.debug("DISCOVERY", f"JSON response: {json.dumps(json_data, indent=2)}")
+
+        # Extract version using JSONPath
+        logger.verbose("DISCOVERY", f"Extracting version from path: {version_path}")
+        try:
+            version_expr = jsonpath_parse(version_path)
+            version_matches = version_expr.find(json_data)
+
+            if not version_matches:
+                raise ConfigError(
+                    f"Version path {version_path!r} did not match anything "
+                    f"in API response"
+                )
+
+            version_str = str(version_matches[0].value)
+        except Exception as err:
+            if isinstance(err, ConfigError):
+                raise
+            raise ConfigError(
+                f"Failed to extract version using path {version_path!r}: {err}"
+            ) from err
+
+        logger.verbose("DISCOVERY", f"Extracted version: {version_str}")
+
+        # Extract download URL using JSONPath
+        logger.verbose(
+            "DISCOVERY", f"Extracting download URL from path: {download_url_path}"
+        )
+        try:
+            url_expr = jsonpath_parse(download_url_path)
+            url_matches = url_expr.find(json_data)
+
+            if not url_matches:
+                raise ConfigError(
+                    f"Download URL path {download_url_path!r} did not match "
+                    f"anything in API response"
+                )
+
+            download_url = str(url_matches[0].value)
+        except Exception as err:
+            if isinstance(err, ConfigError):
+                raise
+            raise ConfigError(
+                f"Failed to extract download URL using path "
+                f"{download_url_path!r}: {err}"
+            ) from err
+
+        logger.verbose("DISCOVERY", f"Download URL: {download_url}")
+
+        return VersionInfo(
+            version=version_str,
+            download_url=download_url,
+            source="api_json",
+        )
+
+    def validate_config(self, app_config: dict[str, Any]) -> list[str]:
+        """Validate api_json strategy configuration.
+
+        Checks for required fields and correct types without making network calls.
+
+        Args:
+            app_config: The app configuration from the recipe.
+
+        Returns:
+            List of error messages (empty if valid).
+
+        """
+        errors = []
+        source = app_config.get("source", {})
+
+        # Check required fields
+        if "api_url" not in source:
+            errors.append("Missing required field: source.api_url")
+        elif not isinstance(source["api_url"], str):
+            errors.append("source.api_url must be a string")
+        elif not source["api_url"].strip():
+            errors.append("source.api_url cannot be empty")
+
+        if "version_path" not in source:
+            errors.append("Missing required field: source.version_path")
+        elif not isinstance(source["version_path"], str):
+            errors.append("source.version_path must be a string")
+        elif not source["version_path"].strip():
+            errors.append("source.version_path cannot be empty")
+        else:
+            # Validate JSONPath syntax
+            from jsonpath_ng import parse as jsonpath_parse
+
+            try:
+                jsonpath_parse(source["version_path"])
+            except Exception as err:
+                errors.append(f"Invalid version_path JSONPath: {err}")
+
+        if "download_url_path" not in source:
+            errors.append("Missing required field: source.download_url_path")
+        elif not isinstance(source["download_url_path"], str):
+            errors.append("source.download_url_path must be a string")
+        elif not source["download_url_path"].strip():
+            errors.append("source.download_url_path cannot be empty")
+        else:
+            # Validate JSONPath syntax
+            from jsonpath_ng import parse as jsonpath_parse
+
+            try:
+                jsonpath_parse(source["download_url_path"])
+            except Exception as err:
+                errors.append(f"Invalid download_url_path JSONPath: {err}")
+
+        # Optional fields validation
+        if "method" in source:
+            method = source["method"]
+            if not isinstance(method, str):
+                errors.append("source.method must be a string")
+            elif method.upper() not in ["GET", "POST"]:
+                errors.append("source.method must be 'GET' or 'POST'")
+
+        if "headers" in source and not isinstance(source["headers"], dict):
+            errors.append("source.headers must be a dictionary")
+
+        if "body" in source and not isinstance(source["body"], dict):
+            errors.append("source.body must be a dictionary")
+
+        return errors
+
+
+# Register this strategy when the module is imported
+register_strategy("api_json", ApiJsonStrategy)

napt/discovery/base.py

@@ -0,0 +1,244 @@
+# Copyright 2025 Roger Cibrian
+#
+# 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.
+
+"""Discovery strategy base protocol and registry for NAPT.
+
+This module defines the foundational components for the discovery system:
+
+- DiscoveryStrategy protocol: Interface that all strategies must implement
+- Strategy registry: Global dict mapping strategy names to implementations
+- Registration and lookup functions: register_strategy() and get_strategy()
+
+The discovery system uses a strategy pattern to support multiple ways
+of obtaining application installers and their versions:
+
+- url_download: Direct download from a static URL (FILE-FIRST)
+- web_scrape: Scrape vendor download pages to find links and extract versions
+    (VERSION-FIRST)
+- api_github: Fetch from GitHub releases API (VERSION-FIRST)
+- api_json: Query JSON API endpoints for version and download URL (VERSION-FIRST)
+
+Design Philosophy:
+    - Strategies are Protocol classes (structural subtyping, not inheritance)
+    - Registration happens at module import time (strategies self-register)
+    - Registry is a simple dict (no complex dependency injection needed)
+    - Each strategy is stateless and can be instantiated on-demand
+
+Protocol Benefits:
+
+Using typing.Protocol instead of ABC allows:
+
+- Duck typing: Classes don't need explicit inheritance
+- Better IDE support: Type checkers verify interface compliance
+- Flexibility: Third-party code can add strategies without touching base
+
+Example:
+    Implementing a custom strategy:
+        ```python
+        from napt.discovery.base import register_strategy, DiscoveryStrategy
+        from pathlib import Path
+        from typing import Any
+        from napt.versioning.keys import DiscoveredVersion
+
+        class MyCustomStrategy:
+            def discover_version(
+                self, app_config: dict[str, Any], output_dir: Path
+            ) -> tuple[DiscoveredVersion, Path, str]:
+                # Implement your discovery logic here
+                ...
+
+        # Register it (typically at module import)
+        register_strategy("my_custom", MyCustomStrategy)
+
+        # Now it can be used in recipes:
+        # source:
+        #   strategy: my_custom
+        #   ...
+        ```
+
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from napt.exceptions import ConfigError
+from napt.versioning.keys import DiscoveredVersion
+
+# -------------------------------
+# Strategy Protocol
+# -------------------------------
+
+
+class DiscoveryStrategy(Protocol):
+    """Protocol for version discovery strategies.
+
+    Each strategy must implement discover_version() which downloads
+    and extracts version information based on the app config.
+
+    Strategies may optionally implement validate_config() to provide
+    strategy-specific configuration validation without network calls.
+    """
+
+    def discover_version(
+        self, app_config: dict[str, Any], output_dir: Path
+    ) -> tuple[DiscoveredVersion, Path, str, dict]:
+        """Discover and download an application version.
+
+        Args:
+            app_config: The app configuration from the recipe
+                (`config["app"]`).
+            output_dir: Directory to download the installer to.
+
+        Returns:
+            A tuple (discovered_version, file_path, sha256, headers), where
+                discovered_version is the version information, file_path is
+                the path to the downloaded file, sha256 is the SHA-256 hash,
+                and headers contains HTTP response headers for caching.
+
+        Raises:
+            ValueError: On discovery or download failures.
+            RuntimeError: On discovery or download failures.
+
+        """
+        ...
+
+    def validate_config(self, app_config: dict[str, Any]) -> list[str]:
+        """Validate strategy-specific configuration (optional).
+
+        This method validates the app configuration for strategy-specific
+        requirements without making network calls or downloading files.
+        Useful for quick feedback during recipe development.
+
+        Args:
+            app_config: The app configuration from the recipe
+                (`config["app"]`).
+
+        Returns:
+            List of error messages. Empty list if configuration is valid.
+            Each error should be a human-readable description of the issue.
+
+        Example:
+            Check required fields:
+                ```python
+                def validate_config(self, app_config):
+                    errors = []
+                    source = app_config.get("source", {})
+                    if "url" not in source:
+                        errors.append("Missing required field: source.url")
+                    return errors
+                ```
+
+        Note:
+            This method is optional; strategies without it will skip validation.
+            Should NOT make network calls or download files. Should check field
+            presence, types, and format only. Used by 'napt validate' command
+            for fast recipe checking.
+
+        """
+        ...
+
+
+# -------------------------------
+# Strategy Registry
+# -------------------------------
+
+_STRATEGY_REGISTRY: dict[str, type[DiscoveryStrategy]] = {}
+
+
+def register_strategy(name: str, strategy_class: type[DiscoveryStrategy]) -> None:
+    """Register a discovery strategy by name in the global registry.
+
+    This function should be called when a strategy module is imported,
+    typically at module level. Registering the same name twice will
+    overwrite the previous registration (allows monkey-patching for tests).
+
+    Args:
+        name: Strategy name (e.g., "url_download"). This is the value
+            used in recipe YAML files under source.strategy. Names should be
+            lowercase with underscores for readability.
+        strategy_class: The strategy class to
+            register. Must implement the DiscoveryStrategy protocol (have a
+            discover_version method with the correct signature).
+
+    Example:
+        Register at module import time:
+            ```python
+            # In discovery/my_strategy.py
+            from .base import register_strategy
+
+            class MyStrategy:
+                def discover_version(self, app_config, output_dir):
+                    ...
+
+            register_strategy("my_strategy", MyStrategy)
+            ```
+
+    Note:
+        No validation is performed at registration time. Type checkers will
+        verify protocol compliance at static analysis time. Runtime errors
+        occur at strategy instantiation or invocation.
+
+    """
+    _STRATEGY_REGISTRY[name] = strategy_class
+
+
+def get_strategy(name: str) -> DiscoveryStrategy:
+    """Get a discovery strategy instance by name from the global registry.
+
+    The strategy is instantiated on-demand (strategies are stateless, so
+    a new instance is created for each call). The strategy module must
+    have been imported first for registration to occur.
+
+    Args:
+        name: Strategy name (e.g., "url_download"). Must exactly match
+            a name registered via register_strategy(). Case-sensitive.
+
+    Returns:
+        A new instance of the requested strategy, ready
+            to use.
+
+    Raises:
+        ConfigError: If the strategy name is not registered. The error message
+            includes a list of available strategies for troubleshooting.
+
+    Example:
+        Get and use a strategy:
+            ```python
+            from napt.discovery import get_strategy
+            strategy = get_strategy("url_download")
+            # Use strategy.discover_version(...)
+            ```
+
+        Handle unknown strategy:
+            ```python
+            try:
+                strategy = get_strategy("nonexistent")
+            except ConfigError as e:
+                print(f"Strategy not found: {e}")
+            ```
+
+    Note:
+        Strategies must be registered before they can be retrieved. The
+        url_download strategy is auto-registered when imported. New strategies
+        can be added by creating a module and registering.
+
+    """
+    if name not in _STRATEGY_REGISTRY:
+        available = ", ".join(_STRATEGY_REGISTRY.keys())
+        raise ConfigError(
+            f"Unknown discovery strategy: {name!r}. Available: {available or '(none)'}"
+        )
+    return _STRATEGY_REGISTRY[name]()