ignition-stack 0.1.0__py3-none-any.whl

ignition_stack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ignition_stack/catalog/__init__.py

@@ -0,0 +1,10 @@
+"""Module + JDBC-driver catalog: schema, loader, verification, download."""
+
+from ignition_stack.catalog.schema import (
+    Catalog,
+    CatalogEntry,
+    JdbcDriverEntry,
+    ModuleEntry,
+)
+
+__all__ = ["Catalog", "CatalogEntry", "JdbcDriverEntry", "ModuleEntry"]

ignition_stack/catalog/download.py

@@ -0,0 +1,145 @@
+"""Host-side cache writer for catalog entries.
+
+The cache lives at ``<project>/modules/cache/`` inside generated projects
+and at any user-supplied path for the standalone ``modules download``
+command. Each artifact is named by its in-container filename so the
+compose-layer mount line is trivial.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+import httpx
+
+from ignition_stack.catalog.schema import SHA256_UNPINNED, CatalogEntry
+from ignition_stack.catalog.verify import sha256_of_file
+
+DOWNLOAD_TIMEOUT_SECONDS = 60.0
+DEFAULT_CACHE_DIR = Path("modules/cache")
+
+
+class DownloadOutcome(StrEnum):
+    DOWNLOADED = "downloaded"
+    COPIED_FROM_LOCAL = "copied-from-local"
+    SKIPPED_MANUAL = "skipped-manual"
+    SKIPPED_CACHED = "skipped-cached"
+
+
+@dataclass(frozen=True, slots=True)
+class DownloadResult:
+    entry_name: str
+    outcome: DownloadOutcome
+    path: Path | None
+    message: str
+
+
+class DownloadError(Exception):
+    """Raised when a network download cannot be completed or fails sha256."""
+
+
+def download_entry(
+    entry: CatalogEntry,
+    cache_dir: Path,
+    *,
+    client: httpx.Client,
+    offline: bool = False,
+) -> DownloadResult:
+    """Materialise ``entry`` into ``cache_dir``.
+
+    Behaviour matrix:
+      - manual + local_source_path exists  -> copy from local
+      - manual + local_source_path missing -> warn-and-skip (config drift)
+      - manual + no local_source_path      -> skip with explanation
+      - already cached + sha matches       -> skip (idempotent)
+      - offline                            -> error if not already cached
+      - normal                             -> http download + sha verify
+    """
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    target = cache_dir / entry.cache_filename()
+
+    if entry.requires_manual_download:
+        return _handle_manual(entry, target)
+
+    if (
+        target.exists()
+        and entry.sha256 != SHA256_UNPINNED
+        and sha256_of_file(target) == entry.sha256
+    ):
+        return DownloadResult(
+            entry.name,
+            DownloadOutcome.SKIPPED_CACHED,
+            target,
+            f"already cached at {target}",
+        )
+
+    if offline:
+        raise DownloadError(
+            f"{entry.name}: --offline set but artifact not in cache "
+            f"({target}). Pre-populate the cache or drop --offline.",
+        )
+
+    if entry.download_url is None:
+        raise DownloadError(
+            f"{entry.name}: no download_url and not marked manual-download.",
+        )
+
+    _http_download(str(entry.download_url), target, client=client)
+
+    if entry.sha256 != SHA256_UNPINNED:
+        actual = sha256_of_file(target)
+        if actual != entry.sha256:
+            target.unlink(missing_ok=True)
+            raise DownloadError(
+                f"{entry.name}: sha256 mismatch after download "
+                f"(expected {entry.sha256}, got {actual}). Cached file removed.",
+            )
+
+    return DownloadResult(
+        entry.name,
+        DownloadOutcome.DOWNLOADED,
+        target,
+        f"downloaded {entry.download_url} -> {target}",
+    )
+
+
+def _handle_manual(entry: CatalogEntry, target: Path) -> DownloadResult:
+    if entry.local_source_path is None:
+        return DownloadResult(
+            entry.name,
+            DownloadOutcome.SKIPPED_MANUAL,
+            None,
+            f"{entry.name} requires manual download (see POST-SETUP.md).",
+        )
+
+    source = Path(entry.local_source_path)
+    if not source.is_file():
+        return DownloadResult(
+            entry.name,
+            DownloadOutcome.SKIPPED_MANUAL,
+            None,
+            (
+                f"WARN: {entry.name} local_source_path missing ({source}). "
+                "Skipping: requires manual download. "
+                "See POST-SETUP.md for instructions."
+            ),
+        )
+
+    shutil.copy2(source, target)
+    return DownloadResult(
+        entry.name,
+        DownloadOutcome.COPIED_FROM_LOCAL,
+        target,
+        f"copied local source {source} -> {target}",
+    )
+
+
+def _http_download(url: str, target: Path, *, client: httpx.Client) -> None:
+    with client.stream("GET", url, follow_redirects=True, timeout=DOWNLOAD_TIMEOUT_SECONDS) as r:
+        r.raise_for_status()
+        with target.open("wb") as fp:
+            for chunk in r.iter_bytes(chunk_size=1024 * 1024):
+                fp.write(chunk)

ignition_stack/catalog/loader.py

@@ -0,0 +1,65 @@
+"""Load and validate modules.yaml into the pydantic Catalog model."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from ignition_stack.catalog.schema import Catalog
+
+
+class CatalogLoadError(Exception):
+    """Raised when modules.yaml cannot be read or fails schema validation."""
+
+
+DEFAULT_CATALOG_NAME = "modules.yaml"
+
+
+def load_catalog(path: Path | None = None) -> Catalog:
+    """Load and validate the catalog.
+
+    When ``path`` is None, the catalog shipped with the installed package is
+    loaded. Otherwise the file at ``path`` is used (test fixtures, alternate
+    catalogs).
+    """
+    yaml_text = _read_yaml_text(path)
+    try:
+        raw = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as exc:
+        raise CatalogLoadError(f"modules.yaml is not valid YAML: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise CatalogLoadError("modules.yaml top-level must be a mapping.")
+
+    try:
+        return Catalog.model_validate(raw)
+    except ValidationError as exc:
+        raise CatalogLoadError(f"modules.yaml failed schema validation:\n{exc}") from exc
+
+
+def _read_yaml_text(path: Path | None) -> str:
+    if path is not None:
+        if not path.is_file():
+            raise CatalogLoadError(f"Catalog not found at {path}.")
+        return path.read_text(encoding="utf-8")
+
+    # Installed wheels: modules.yaml is force-included as package data at
+    # ignition_stack/modules.yaml. Editable dev installs: it lives at the
+    # repo root next to pyproject.toml.
+    try:
+        bundled = resources.files("ignition_stack").joinpath(DEFAULT_CATALOG_NAME)
+        if bundled.is_file():
+            return bundled.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError, ModuleNotFoundError):
+        pass
+
+    repo_root = Path(__file__).resolve().parents[2]
+    dev_path = repo_root / DEFAULT_CATALOG_NAME
+    if not dev_path.is_file():
+        raise CatalogLoadError(
+            f"Bundled catalog not found (looked for {dev_path}).",
+        )
+    return dev_path.read_text(encoding="utf-8")

ignition_stack/catalog/schema.py

@@ -0,0 +1,158 @@
+"""Pydantic schema for modules.yaml.
+
+The catalog is the single source of truth for which .modl modules and JDBC
+drivers the CLI knows how to download, cache-verify, and wire into a
+generated stack. One file (`modules.yaml` at the repo root) is read at
+both `modules` subcommand time and `init` time.
+
+Two entry kinds: third-party Ignition modules (.modl) and JDBC drivers
+(.jar). They are distinct shapes because Phase 1 confirmed the module
+accept env vars (`ACCEPT_MODULE_LICENSES`, `ACCEPT_MODULE_CERTS`) take
+**fully-qualified module identifiers, not paths** - while the
+volume-mount needs the in-container install path.
+JDBC drivers have no identifier and no accept-license env vars; they
+are simply files in `user-lib/jdbc/`.
+
+A discriminated union (`kind: module | jdbc_driver`) keeps the two
+shapes statically separable so the compose generator emits the right
+env vars for each.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+
+# Sentinel for catalog entries whose sha256 has not yet been pinned by a
+# maintainer (e.g. fresh release the maintainer is in the middle of
+# bumping). `modules validate` rejects this so a half-bumped catalog
+# cannot ship.
+SHA256_UNPINNED = "UNPINNED"
+
+
+class _EntryBase(BaseModel):
+    """Fields shared by every catalog entry."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: Annotated[
+        str,
+        Field(
+            min_length=1,
+            pattern=r"^[a-z0-9][a-z0-9-]*$",
+            description="Slug used in CLI output and as the cache filename stem.",
+        ),
+    ]
+    vendor: Annotated[str, Field(min_length=1)]
+    ignition_versions: Annotated[
+        list[str],
+        Field(
+            min_length=1,
+            description=(
+                "Exact Ignition versions this entry is verified against "
+                "(e.g. ['8.3.6', '8.3.7']). Resolution is exact-match: bump "
+                "the list when a new Ignition patch is validated."
+            ),
+        ),
+    ]
+    download_url: HttpUrl | None = Field(
+        default=None,
+        description=("Public download URL. Required unless requires_manual_download is true."),
+    )
+    sha256: Annotated[
+        str,
+        Field(
+            pattern=rf"^([0-9a-f]{{64}}|{SHA256_UNPINNED})$",
+            description=(
+                f"Lowercase hex sha256 of the artifact, or '{SHA256_UNPINNED}' "
+                "while a maintainer is mid-bump (rejected by `modules validate`)."
+            ),
+        ),
+    ]
+    install_path: Annotated[
+        str,
+        Field(
+            min_length=1,
+            description=(
+                "Fully-qualified in-container destination path. The compose "
+                "layer mounts/copies the cached artifact here."
+            ),
+        ),
+    ]
+    requires_license_env: str | None = Field(
+        default=None,
+        description=(
+            "Name of an env var the user must set with their license key. "
+            "None for community-usable modules and unlicensed drivers."
+        ),
+    )
+    requires_manual_download: bool = Field(
+        default=False,
+        description=(
+            "True when the artifact has no public URL (e.g. EA-gated). "
+            "`modules download` skips these unless local_source_path is set "
+            "and points at an existing file."
+        ),
+    )
+    local_source_path: str | None = Field(
+        default=None,
+        description=(
+            "Optional maintainer-configured absolute path on the host to a "
+            "locally-stored copy. Used only when requires_manual_download is "
+            "true; when present and the file exists, `download` copies it "
+            "into the cache instead of fetching."
+        ),
+    )
+
+    def cache_filename(self) -> str:
+        """Filename used inside the host-side cache dir."""
+        return PurePosixPath(self.install_path).name
+
+
+class ModuleEntry(_EntryBase):
+    """A third-party Ignition `.modl` module."""
+
+    kind: Literal["module"] = "module"
+    module_identifier: Annotated[
+        str,
+        Field(
+            min_length=1,
+            pattern=r"^[a-z0-9.]+$",
+            description=(
+                "Fully-qualified module identifier (e.g. "
+                "'com.cirruslink.mqtt.engine.gateway'). Used verbatim in "
+                "ACCEPT_MODULE_LICENSES and ACCEPT_MODULE_CERTS. NOT a path."
+            ),
+        ),
+    ]
+
+
+class JdbcDriverEntry(_EntryBase):
+    """A JDBC driver `.jar` dropped into `user-lib/jdbc/`."""
+
+    kind: Literal["jdbc_driver"] = "jdbc_driver"
+
+
+CatalogEntry = Annotated[ModuleEntry | JdbcDriverEntry, Field(discriminator="kind")]
+
+
+class Catalog(BaseModel):
+    """Top-level shape of modules.yaml."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    version: Annotated[int, Field(ge=1, description="Schema version; bump on breaking change.")]
+    entries: Annotated[list[CatalogEntry], Field(min_length=1)]
+
+    def by_name(self, name: str) -> CatalogEntry:
+        """Look up an entry by slug; raises KeyError if absent."""
+        for entry in self.entries:
+            if entry.name == name:
+                return entry
+        raise KeyError(name)
+
+    def for_ignition(self, ignition_version: str) -> list[CatalogEntry]:
+        """Entries verified against the given exact Ignition version."""
+        return [e for e in self.entries if ignition_version in e.ignition_versions]

ignition_stack/catalog/verify.py

@@ -0,0 +1,72 @@
+"""Reachability + sha256 verification for catalog entries."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from ignition_stack.catalog.schema import SHA256_UNPINNED, CatalogEntry
+
+REACHABILITY_TIMEOUT_SECONDS = 10.0
+
+
+@dataclass(frozen=True, slots=True)
+class VerifyIssue:
+    """One problem found while validating an entry."""
+
+    entry_name: str
+    reason: str
+
+
+def verify_reachable(entry: CatalogEntry, client: httpx.Client) -> VerifyIssue | None:
+    """HEAD-check the entry's download URL. None means reachable.
+
+    Entries that are manual-download are skipped (no URL to check). The
+    response must be 2xx; many CDNs reject HEAD with 405 but accept GET,
+    so a 405 falls through to a small range GET before declaring failure.
+    """
+    if entry.requires_manual_download:
+        return None
+    if entry.download_url is None:
+        return VerifyIssue(entry.name, "no download_url and not marked manual")
+
+    url = str(entry.download_url)
+    try:
+        response = client.head(url, follow_redirects=True, timeout=REACHABILITY_TIMEOUT_SECONDS)
+        if response.status_code == 405:
+            response = client.get(
+                url,
+                follow_redirects=True,
+                timeout=REACHABILITY_TIMEOUT_SECONDS,
+                headers={"Range": "bytes=0-0"},
+            )
+        if response.status_code >= 400:
+            return VerifyIssue(entry.name, f"HTTP {response.status_code} for {url}")
+    except httpx.HTTPError as exc:
+        return VerifyIssue(entry.name, f"unreachable: {exc} ({url})")
+    return None
+
+
+def sha256_of_file(path: Path) -> str:
+    """Lowercase hex sha256 digest of a file on disk."""
+    h = hashlib.sha256()
+    with path.open("rb") as fp:
+        for chunk in iter(lambda: fp.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def verify_checksum(entry: CatalogEntry, file_path: Path) -> VerifyIssue | None:
+    """Check the file at ``file_path`` matches the entry's pinned sha256."""
+    if entry.sha256 == SHA256_UNPINNED:
+        return VerifyIssue(entry.name, "sha256 is UNPINNED (maintainer must pin before release)")
+    actual = sha256_of_file(file_path)
+    if actual != entry.sha256:
+        return VerifyIssue(
+            entry.name,
+            f"sha256 mismatch: expected {entry.sha256}, got {actual}",
+        )
+    return None