napt 0.3.1__py3-none-any.whl

napt/io/download.py

@@ -0,0 +1,357 @@
+# 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.
+
+"""Robust HTTP(S) file download for NAPT.
+
+This module provides production-grade file downloading with features designed
+for reliability, reproducibility, and efficiency in automated packaging workflows.
+
+Key Features:
+
+- **Retry Logic with Exponential Backoff** - Automatically retries on
+  transient failures (429, 500, 502, 503, 504) with exponential backoff.
+  Configurable via urllib3.util.Retry.
+- **Conditional Requests (HTTP 304 Not Modified)** - Supports ETag and
+  Last-Modified headers to avoid re-downloading unchanged files.
+- **Atomic Writes** - Downloads to temporary .part files with atomic rename
+  on success to prevent partial files.
+- **Integrity Verification** - SHA-256 hashing during download with
+  optional checksum validation. Corrupted files are automatically removed.
+- **Smart Filename Detection** - Respects Content-Disposition headers,
+  falls back to URL path, handles edge cases.
+- **Stable ETags** - Forces Accept-Encoding: identity to avoid
+  representation-specific ETags and prevent false cache misses.
+
+NotModifiedError is raised when a conditional request returns HTTP 304
+(not an error condition). The module defines DEFAULT_CHUNK (1 MiB) as the
+stream chunk size, balancing memory usage vs. progress granularity.
+
+Example:
+    Basic download:
+        ```python
+        from pathlib import Path
+        from napt.io import download_file
+
+        path, sha256, headers = download_file(
+            url="https://example.com/installer.msi",
+            destination_folder=Path("./downloads"),
+        )
+        print(f"Downloaded to {path}")
+        print(f"SHA-256: {sha256}")
+        ```
+
+    Conditional download (avoid re-downloading):
+        ```python
+        from napt.io import NotModifiedError
+
+        try:
+            path, sha256, headers = download_file(
+                url="https://example.com/installer.msi",
+                destination_folder=Path("./downloads"),
+                etag=previous_etag,
+            )
+        except NotModifiedError:
+            print("File unchanged, using cached version")
+        ```
+
+    Checksum validation:
+        ```python
+        try:
+            path, sha256, headers = download_file(
+                url="https://example.com/installer.msi",
+                destination_folder=Path("./downloads"),
+                expected_sha256="abc123...",
+            )
+        except NetworkError as e:
+            print(f"Checksum mismatch: {e}")
+        ```
+
+Note:
+    Progress output goes to stdout (can be captured/redirected). User-Agent
+    identifies NAPT to help with debugging/support. All HTTP errors are
+    chained for better debugging. Timeouts are per-request, not total
+    download time.
+
+    Identity encoding stabilizes ETags: CDNs like Cloudflare compute
+    representation-specific ETags, so requesting gzip vs identity yields
+    different ETags for the same content, causing unnecessary re-downloads.
+
+    Atomic writes prevent partial files from appearing in the destination,
+    which is critical for automation where another process might start using
+    a file before download completes. Stream hashing computes SHA-256 while
+    streaming to avoid a second file read, improving I/O efficiency for
+    large installers.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+import hashlib
+from pathlib import Path
+import time
+from urllib.parse import urlparse
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from napt.exceptions import ConfigError, NetworkError
+
+# Stream size per chunk (1 MiB). Tune up/down if needed.
+DEFAULT_CHUNK = 1024 * 1024
+
+
+class NotModifiedError(Exception):
+    """Raised when a conditional request (If-None-Match / If-Modified-Since)
+    returns HTTP 304 Not Modified. Caller can treat this as "no work to do".
+    """
+
+
+def _filename_from_cd(content_disposition: str) -> str | None:
+    """Extracts a filename from a Content-Disposition header if present.
+
+    Parses headers like 'attachment; filename="setup.msi"' and returns the
+    filename value.
+    """
+    if not content_disposition:
+        return None
+    parts = [s.strip() for s in content_disposition.split(";")]
+    for part in parts:
+        if part.lower().startswith("filename="):
+            value = part.split("=", 1)[1].strip().strip('"')
+            return value or None
+    return None
+
+
+def _filename_from_url(url: str) -> str:
+    """Derive a filename from the URL path. Fallback to a generic name if empty."""
+    name = Path(urlparse(url).path).name
+    return name or "download.bin"
+
+
+def _sha256_iter(chunks: Iterable[bytes]) -> str:
+    """Compute SHA-256 from an iterator of byte chunks (stream-friendly)."""
+    h = hashlib.sha256()
+    for c in chunks:
+        h.update(c)
+    return h.hexdigest()
+
+
+def make_session() -> requests.Session:
+    """Create a requests.Session with sane retry/backoff defaults.
+
+    Retries on common transient status codes, applies exponential backoff,
+    and sets a helpful User-Agent to avoid being blocked.
+
+    Note:
+        Forces Accept-Encoding: identity to request raw (uncompressed) bytes.
+        Many CDNs compute representation-specific ETags (e.g., gzip vs identity),
+        which can cause conditional requests to miss and trigger unnecessary
+        re-downloads. Pinning identity stabilizes ETags for binary installers
+        (MSI/EXE/MSIX/ZIP), which are already compressed.
+    """
+    s = requests.Session()
+    retries = Retry(
+        total=5,
+        backoff_factor=0.5,
+        status_forcelist=(429, 500, 502, 503, 504),
+        allowed_methods=("GET", "HEAD"),
+        raise_on_status=False,
+    )
+    s.headers.update(
+        {
+            "User-Agent": "napt/0.1 (+https://github.com/RogerCibrian/notapkgtool)",
+            # Request the raw, uncompressed representation to keep ETags stable
+            # across runs and avoid spurious 200s when a CDN flips to gzip.
+            "Accept-Encoding": "identity",
+        }
+    )
+    s.mount("http://", HTTPAdapter(max_retries=retries))
+    s.mount("https://", HTTPAdapter(max_retries=retries))
+    return s
+
+
+def download_file(
+    url: str,
+    destination_folder: Path,
+    *,
+    expected_sha256: str | None = None,
+    validate_content_type: bool = False,
+    timeout: int = 60,
+    etag: str | None = None,
+    last_modified: str | None = None,
+) -> tuple[Path, str, dict]:
+    """Download a URL to destination_folder with robustness and reproducibility.
+
+    Follows redirects and retries transient failures. Writes to <filename>.part
+    then renames to <filename> on success (atomic). Sends conditional headers
+    if etag/last_modified provided. Validates checksum if expected_sha256 is set.
+
+    Args:
+        url: Source URL.
+        destination_folder: Folder to save into (created if missing).
+        expected_sha256: Optional known SHA-256 (hex). If set and mismatched,
+            raises NetworkError.
+        validate_content_type: If True, rejects responses with text/html content-type.
+        timeout: Per-request timeout (seconds).
+        etag: Previous ETag to use for If-None-Match (conditional GET).
+        last_modified: Previous Last-Modified to use for If-Modified-Since
+            (conditional GET).
+
+    Returns:
+        Tuple of file path, SHA-256 hash, and HTTP response headers.
+
+    Raises:
+        NotModifiedError: On HTTP 304 (conditional request satisfied).
+        NetworkError: For non-2xx responses (after retries) or checksum mismatch.
+        ConfigError: For content-type mismatch.
+
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    destination_folder = Path(destination_folder)
+    destination_folder.mkdir(parents=True, exist_ok=True)
+
+    headers: dict[str, str] = {}
+    if etag:
+        headers["If-None-Match"] = etag
+        logger.verbose("HTTP", f"Using conditional request with ETag: {etag}")
+    elif last_modified:
+        headers["If-Modified-Since"] = last_modified
+        logger.verbose(
+            "HTTP", f"Using conditional request with Last-Modified: {last_modified}"
+        )
+
+    logger.verbose("HTTP", f"GET {url}")
+    logger.verbose(
+        "HTTP",
+        "Request headers: Accept-Encoding: identity, User-Agent: napt/0.1.0",
+    )
+
+    with make_session() as session:
+        # Stream response so we can hash while writing.
+        resp = session.get(
+            url, stream=True, allow_redirects=True, timeout=timeout, headers=headers
+        )
+
+        # Log redirects
+        if len(resp.history) > 0:
+            for hist in resp.history:
+                logger.verbose(
+                    "HTTP",
+                    (
+                        f"Redirect {hist.status_code} -> "
+                        f"{hist.headers.get('Location', 'unknown')}"
+                    ),
+                )
+
+        # Conditional request satisfied: nothing changed since last time.
+        if resp.status_code == 304:
+            logger.verbose("HTTP", "Response: 304 Not Modified")
+            resp.close()
+            raise NotModifiedError("Remote content not modified (HTTP 304).")
+
+        # Raise for other HTTP errors after retries.
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError as err:
+            # Chain for better context.
+            raise NetworkError(f"download failed for {url}: {err}") from err
+
+        logger.verbose("HTTP", f"Response: {resp.status_code} {resp.reason}")
+
+        # Content-Disposition beats URL when naming the file.
+        cd_name = _filename_from_cd(resp.headers.get("Content-Disposition", ""))
+        filename = cd_name or _filename_from_url(resp.url)
+        target = destination_folder / filename
+
+        # Log response details
+        content_length = resp.headers.get("Content-Length", "unknown")
+        if content_length != "unknown":
+            size_mb = int(content_length) / (1024 * 1024)
+            logger.verbose(
+                "HTTP", f"Content-Length: {content_length} ({size_mb:.1f} MB)"
+            )
+            etag_value = resp.headers.get("ETag", "not provided")
+            logger.verbose("HTTP", f"ETag: {etag_value}")
+            cd_header = resp.headers.get("Content-Disposition", "not provided")
+            logger.verbose("HTTP", f"Content-Disposition: {cd_header}")
+
+        # Optional content-type sanity check.
+        if validate_content_type:
+            ctype = resp.headers.get("Content-Type", "")
+            if "text/html" in ctype.lower():
+                resp.close()
+                raise ConfigError(f"expected binary, got content-type={ctype}")
+
+        total_size = int(resp.headers.get("Content-Length", "0") or 0)
+
+        tmp = target.with_suffix(target.suffix + ".part")
+        logger.verbose("FILE", f"Downloading to: {tmp}")
+
+        sha = hashlib.sha256()
+        downloaded = 0
+        last_percent = -1
+        started_at = time.time()
+
+        with tmp.open("wb") as f:
+            for chunk in resp.iter_content(chunk_size=DEFAULT_CHUNK):
+                if not chunk:
+                    continue
+                f.write(chunk)
+                sha.update(chunk)
+                downloaded += len(chunk)
+
+                # Optional lightweight progress indicator.
+                if total_size:
+                    pct = int(downloaded * 100 / total_size)
+                    if pct != last_percent:
+                        print(f"download progress: {pct}%", end="\r")
+                        last_percent = pct
+
+        # Cleanup response socket.
+        resp.close()
+
+        digest = sha.hexdigest()
+        logger.verbose("FILE", f"SHA-256: {digest} (computed during download)")
+
+        # Atomically "commit" the file.
+        logger.verbose("FILE", f"Atomic rename: {tmp.name} -> {target.name}")
+        tmp.replace(target)
+
+        # Validate checksum if the caller expects a specific digest.
+        if expected_sha256 and digest.lower() != expected_sha256.lower():
+            logger.verbose(
+                "FILE", f"Checksum mismatch! Expected: {expected_sha256}, Got: {digest}"
+            )
+            try:
+                target.unlink()
+            except OSError:
+                pass
+            raise NetworkError(
+                f"sha256 mismatch for {filename}: got {digest}, "
+                f"expected {expected_sha256}"
+            )
+
+        elapsed = time.time() - started_at
+        # Always show completion message
+        logger.step(1, 1, f"Download complete: {target} ({digest}) in {elapsed:.1f}s")
+        # Show detailed info in verbose mode
+        logger.verbose("FILE", f"Download complete: {target}")
+        logger.verbose("FILE", f"Time elapsed: {elapsed:.1f}s")
+
+        # Hand back headers the caller may want to persist (ETag, Last-Modified).
+        return target, digest, dict(resp.headers)

napt/io/upload.py

@@ -0,0 +1,37 @@
+# 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.
+
+"""File upload functionality for NAPT.
+
+This module provides file upload capabilities for deploying packages to
+Intune and other storage providers. Currently focused on Microsoft Intune
+Win32 app deployment with support for .intunewin package uploads.
+
+The module handles authentication, chunked uploads, encryption requirements,
+and retry logic specific to Intune's Graph API endpoints.
+
+Example:
+    Basic Intune upload:
+        ```python
+        from pathlib import Path
+        from napt.io.upload import upload_to_intune
+
+        result = upload_to_intune(
+            intunewin_path=Path("./MyApp.intunewin"),
+            app_id="12345678-1234-1234-1234-123456789abc",
+            access_token="eyJ0eXAiOi...",
+        )
+        print(f"Upload complete: {result}")
+        ```
+"""

napt/logging.py

@@ -0,0 +1,230 @@
+# 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.
+
+"""Logging interface for NAPT.
+
+This module provides a configurable logging interface that library modules
+can use for output without depending on the CLI. The logger can be configured
+globally or passed as a parameter for better isolation.
+
+The logger supports four output levels:
+
+- Step: Always printed (for progress indicators)
+- Warning: Always printed (for important warnings that users should see)
+- Verbose: Only printed when verbose mode is enabled
+- Debug: Only printed when debug mode is enabled (implies verbose)
+
+Example:
+    Configure global logger:
+        ```python
+        from napt.logging import get_logger, set_global_logger
+
+        logger = get_logger(verbose=True, debug=False)
+        set_global_logger(logger)
+        ```
+
+    Use in library code:
+        ```python
+        from napt.logging import get_logger
+
+        logger = get_logger()
+        logger.step(1, 4, "Loading configuration...")
+        logger.warning("DETECTION", "Could not extract MSI metadata")
+        logger.verbose("STATE", "Loaded state from file")
+        logger.debug("VERSION", "Trying backend: msilib...")
+        ```
+
+    Use with dependency injection:
+
+        def my_function(logger=None):
+            if logger is None:
+                logger = get_logger()
+            logger.verbose("MODULE", "Processing...")
+
+Note:
+    The default logger is silent (verbose=False, debug=False), so library
+    functions won't print anything unless explicitly configured. The CLI
+    configures the global logger when commands are executed.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Logger(Protocol):
+    """Protocol for logger implementations."""
+
+    def step(self, step: int, total: int, message: str) -> None:
+        """Print a step indicator for non-verbose mode.
+
+        Args:
+            step: Current step number (1-based).
+            total: Total number of steps.
+            message: Step description.
+        """
+        ...
+
+    def warning(self, prefix: str, message: str) -> None:
+        """Print a warning message (always visible).
+
+        Args:
+            prefix: Message prefix (e.g., "DETECTION", "BUILD").
+            message: Warning message.
+        """
+        ...
+
+    def verbose(self, prefix: str, message: str) -> None:
+        """Print a verbose log message.
+
+        Args:
+            prefix: Message prefix (e.g., "STATE", "BUILD").
+            message: Log message.
+        """
+        ...
+
+    def debug(self, prefix: str, message: str) -> None:
+        """Print a debug log message.
+
+        Args:
+            prefix: Message prefix (e.g., "VERSION", "HTTP").
+            message: Log message.
+        """
+        ...
+
+
+class DefaultLogger:
+    """Default logger implementation that prints to stdout.
+
+    This logger respects verbose and debug flags and formats output
+    consistently with the CLI output format.
+    """
+
+    def __init__(self, verbose: bool = False, debug: bool = False) -> None:
+        """Initialize logger with verbosity settings.
+
+        Args:
+            verbose: If True, print verbose messages.
+            debug: If True, print debug messages (implies verbose).
+        """
+        self._verbose = verbose or debug
+        self._debug = debug
+
+    def step(self, step: int, total: int, message: str) -> None:
+        """Print a step indicator for non-verbose mode."""
+        print(f"[{step}/{total}] {message}")
+
+    def warning(self, prefix: str, message: str) -> None:
+        """Print a warning message (always visible)."""
+        print(f"[{prefix}] {message}")
+
+    def verbose(self, prefix: str, message: str) -> None:
+        """Print a verbose log message (only when verbose mode is active)."""
+        if self._verbose:
+            print(f"[{prefix}] {message}")
+
+    def debug(self, prefix: str, message: str) -> None:
+        """Print a debug log message (only when debug mode is active)."""
+        if self._debug:
+            print(f"[{prefix}] {message}")
+
+
+class SilentLogger:
+    """Logger that suppresses all output.
+
+    Useful for programmatic usage when output is not desired.
+    """
+
+    def step(self, step: int, total: int, message: str) -> None:
+        """Suppress step output."""
+        pass
+
+    def warning(self, prefix: str, message: str) -> None:
+        """Suppress warning output."""
+        pass
+
+    def verbose(self, prefix: str, message: str) -> None:
+        """Suppress verbose output."""
+        pass
+
+    def debug(self, prefix: str, message: str) -> None:
+        """Suppress debug output."""
+        pass
+
+
+# Global logger instance (defaults to silent)
+_global_logger: Logger = SilentLogger()
+
+
+def get_logger(verbose: bool = False, debug: bool = False) -> Logger:
+    """Get a logger instance with specified verbosity.
+
+    Args:
+        verbose: If True, logger will print verbose messages.
+        debug: If True, logger will print debug messages (implies verbose).
+
+    Returns:
+        A logger instance configured with the specified verbosity.
+
+    Example:
+        Get a verbose logger:
+            ```python
+            logger = get_logger(verbose=True)
+            logger.verbose("MODULE", "Processing...")
+            ```
+
+        Get a debug logger:
+            ```python
+            logger = get_logger(debug=True)
+            logger.debug("MODULE", "Debug info...")
+            ```
+    """
+    return DefaultLogger(verbose=verbose, debug=debug)
+
+
+def get_global_logger() -> Logger:
+    """Get the global logger instance.
+
+    Returns:
+        The current global logger instance.
+
+    Note:
+        The default global logger is silent. Use set_global_logger() to
+        configure it, or pass a logger instance directly to functions.
+    """
+    return _global_logger
+
+
+def set_global_logger(logger: Logger) -> None:
+    """Set the global logger instance.
+
+    Args:
+        logger: Logger instance to use as the global logger.
+
+    Example:
+        Configure global logger from CLI:
+            ```python
+            from napt.logging import get_logger, set_global_logger
+
+            logger = get_logger(verbose=args.verbose, debug=args.debug)
+            set_global_logger(logger)
+            ```
+
+    Note:
+        This affects all library functions that use get_logger() without
+        passing a logger instance. For better isolation, pass logger
+        instances directly to functions instead of using the global logger.
+    """
+    global _global_logger
+    _global_logger = logger

napt/policy/__init__.py

@@ -0,0 +1,50 @@
+# 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.
+
+"""Deployment policy and update management for NAPT.
+
+This module provides policy enforcement for application updates including
+version comparison strategies, hash-based change detection, and deployment
+wave/ring management.
+
+Modules:
+    updates: Update policies for deciding when to stage new application versions.
+
+Example:
+    Basic usage:
+        ```python
+        from napt.policy import UpdatePolicy, should_stage
+
+        policy = UpdatePolicy(
+            strategy="version_then_hash",
+            comparator="semver",
+        )
+
+        stage_it = should_stage(
+            remote_version="1.2.0",
+            remote_hash="abc123...",
+            current_version="1.1.9",
+            current_hash="def456...",
+            policy=policy,
+        )
+        print(f"Should stage: {stage_it}")  # True
+        ```
+
+"""
+
+# Future: Import when updates.py is fully implemented
+# from .updates import UpdatePolicy, should_stage
+# __all__ = ["UpdatePolicy", "should_stage"]
+
+__all__ = []