ignition-stack 0.1.1__tar.gz → 0.3.0__tar.gz

{ignition_stack-0.1.1 → ignition_stack-0.3.0}/.gitignore

@@ -30,8 +30,3 @@ Thumbs.db
 .env
 .env.local
 *.env
-
-# Phase-1 POC artifacts (transient container outputs)
-scripts/seeding-poc/runs/
-scripts/seeding-poc/.modl-cache/
-# Screenshots ARE committed - they're the matrix's evidence.

{ignition_stack-0.1.1 → ignition_stack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ignition-stack
-Version: 0.1.1
+Version: 0.3.0
 Summary: CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements
 Author-email: Eric Knorr <etknorr@gmail.com>
 License: MIT
@@ -25,9 +25,6 @@ Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3; extra == 'dev'
 Requires-Dist: ruff>=0.7; extra == 'dev'
-Provides-Extra: poc
-Requires-Dist: httpx>=0.27; extra == 'poc'
-Requires-Dist: playwright>=1.49; extra == 'poc'
 Description-Content-Type: text/markdown
 
 # ignition-stack

ignition_stack-0.3.0/builtin_modules.yaml

@@ -0,0 +1,122 @@
+# Catalog of the built-in IA modules that ship inside the Ignition gateway
+# image. Used to translate a gateway's `disable_builtins` slugs into the
+# GATEWAY_MODULES_ENABLED whitelist the engine emits (enabled = all built-ins
+# minus the disabled ones, plus any third-party module identifiers).
+#
+# Why this file exists:
+#   GATEWAY_MODULES_ENABLED is a strict WHITELIST, not a blocklist - anything
+#   not listed is quarantined at boot (verified live on 8.3.6). So "disable
+#   Vision" can only be expressed as "enable every built-in except Vision".
+#   That inversion needs the COMPLETE built-in set; an incomplete list would
+#   silently quarantine the modules we forgot to enumerate. This file is that
+#   complete set, and tests/test_builtin_catalog.py (marked `smoke`) re-derives
+#   it from the live image so a stale list fails CI loudly instead of dropping
+#   modules silently.
+#
+# Provenance (how to regenerate when bumping the Ignition image):
+#   1. Boot the pinned image with no whitelist so every built-in loads:
+#        docker run --rm -e ACCEPT_IGNITION_EULA=Y -e GATEWAY_ADMIN_PASSWORD=x \
+#          inductiveautomation/ignition:<tag>
+#   2. Read the loaded set from the gateway log lines:
+#        Starting up module '<identifier>' ... module-name=<name>
+#   3. Update `ignition_version` and the `modules` list below to match.
+#   The smoke guard test automates this comparison.
+#
+# `identifier` is the fully-qualified module id used verbatim in
+# GATEWAY_MODULES_ENABLED. `slug` is the friendly kebab name a user puts in
+# `disable_builtins`. `name` is the gateway's display name (for wizard labels).
+
+version: 1
+
+# The exact Ignition image tag this built-in set was captured from. The guard
+# test only asserts a match when the running image reports this version.
+ignition_version: "8.3.6"
+
+modules:
+  - slug: alarm-notification
+    identifier: com.inductiveautomation.alarm-notification
+    name: Alarm Notification
+  - slug: allen-bradley-driver
+    identifier: com.inductiveautomation.opcua.drivers.ablegacy
+    name: Allen-Bradley Driver
+  - slug: bacnet-driver
+    identifier: com.inductiveautomation.opcua.drivers.bacnet
+    name: BACnet Driver
+  - slug: enterprise-administration
+    identifier: com.inductiveautomation.eam
+    name: Enterprise Administration
+  - slug: event-streams
+    identifier: com.inductiveautomation.eventstream
+    name: Event Streams
+  - slug: historian-core
+    identifier: com.inductiveautomation.historian
+    name: Historian Core
+  - slug: kafka-connector
+    identifier: com.inductiveautomation.connectors.kafka
+    name: Kafka Connector
+  - slug: legacy-dnp3-driver
+    identifier: com.inductiveautomation.opcua.drivers.dnp3
+    name: Legacy DNP3 Driver
+  - slug: logix-driver
+    identifier: com.inductiveautomation.opcua.drivers.logix
+    name: Logix Driver
+  - slug: mariadb-jdbc-driver
+    identifier: com.inductiveautomation.jdbc.mariadb
+    name: MariaDB JDBC Driver
+  - slug: micro800-driver
+    identifier: com.inductiveautomation.opcua.drivers.micro800
+    name: Micro800 Driver
+  - slug: mitsubishi-driver
+    identifier: com.inductiveautomation.opcua.drivers.mitsubishi
+    name: Mitsubishi Driver
+  - slug: modbus-driver
+    identifier: com.inductiveautomation.opcua.drivers.modbus
+    name: Modbus Driver
+  - slug: mssql-jdbc-driver
+    identifier: com.inductiveautomation.jdbc.mssql
+    name: MSSQL JDBC Driver
+  - slug: omron-driver
+    identifier: com.inductiveautomation.opcua.drivers.omron
+    name: Omron Driver
+  - slug: opc-ua
+    identifier: com.inductiveautomation.opcua
+    name: OPC-UA
+  - slug: perspective
+    identifier: com.inductiveautomation.perspective
+    name: Perspective
+  - slug: postgresql-jdbc-driver
+    identifier: com.inductiveautomation.jdbc.postgresql
+    name: PostgreSQL JDBC Driver
+  - slug: reporting
+    identifier: com.inductiveautomation.reporting
+    name: Reporting
+  - slug: sfc
+    identifier: com.inductiveautomation.sfc
+    name: SFC
+  - slug: siemens-drivers
+    identifier: com.inductiveautomation.opcua.drivers.siemens
+    name: Siemens Drivers
+  - slug: siemens-enhanced-driver
+    identifier: com.inductiveautomation.opcua.drivers.siemens-symbolic
+    name: Siemens Enhanced Driver
+  - slug: sms-notification
+    identifier: com.inductiveautomation.sms-notification
+    name: SMS Notification
+  - slug: sql-bridge
+    identifier: com.inductiveautomation.sqlbridge
+    name: SQL Bridge
+  - slug: sql-historian
+    identifier: com.inductiveautomation.historian.sql
+    name: SQL Historian
+  - slug: symbol-factory
+    identifier: com.inductiveautomation.symbol-factory
+    name: Symbol Factory
+  - slug: udp-and-tcp-drivers
+    identifier: com.inductiveautomation.opcua.drivers.tcpudp
+    name: UDP and TCP Drivers
+  - slug: vision
+    identifier: com.inductiveautomation.vision
+    name: Vision
+  - slug: webdev
+    identifier: com.inductiveautomation.webdev
+    name: WebDev

ignition_stack-0.3.0/ignition_stack/__init__.py

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

ignition_stack-0.3.0/ignition_stack/catalog/builtins.py

@@ -0,0 +1,171 @@
+"""Load and query the built-in IA module catalog (``builtin_modules.yaml``).
+
+The third-party catalog (``modules.yaml`` + ``catalog/schema.py``) covers
+modules the CLI *adds*. This module covers the modules that *already ship*
+inside the gateway image, which the engine needs in order to translate a
+gateway's ``disable_builtins`` slugs into a ``GATEWAY_MODULES_ENABLED``
+whitelist.
+
+The whitelist is strict: anything not listed is quarantined at boot. So
+"disable Vision" is expressed as "enable every built-in except Vision",
+which requires the *complete* built-in set - hence a pinned data file plus a
+smoke guard test that re-derives it from the live image.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Annotated
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+
+class BuiltinCatalogLoadError(Exception):
+    """Raised when builtin_modules.yaml cannot be read or fails validation."""
+
+
+DEFAULT_BUILTIN_CATALOG_NAME = "builtin_modules.yaml"
+
+
+class BuiltinModule(BaseModel):
+    """One built-in IA module that ships inside the gateway image."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    slug: Annotated[
+        str,
+        Field(
+            min_length=1,
+            pattern=r"^[a-z0-9][a-z0-9-]*$",
+            description="Friendly kebab name a user puts in `disable_builtins`.",
+        ),
+    ]
+    identifier: Annotated[
+        str,
+        Field(
+            min_length=1,
+            pattern=r"^[a-z0-9.-]+$",
+            description="Fully-qualified module id, used verbatim in GATEWAY_MODULES_ENABLED.",
+        ),
+    ]
+    name: Annotated[str, Field(min_length=1, description="Gateway display name (wizard label).")]
+
+
+class BuiltinCatalog(BaseModel):
+    """Top-level shape of builtin_modules.yaml."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    version: Annotated[int, Field(ge=1)]
+    ignition_version: Annotated[
+        str,
+        Field(min_length=1, description="Image tag this built-in set was captured from."),
+    ]
+    modules: Annotated[list[BuiltinModule], Field(min_length=1)]
+
+    @field_validator("modules")
+    @classmethod
+    def _slugs_unique(cls, modules: list[BuiltinModule]) -> list[BuiltinModule]:
+        slugs = [m.slug for m in modules]
+        dupes = sorted({s for s in slugs if slugs.count(s) > 1})
+        if dupes:
+            raise ValueError(f"duplicate built-in slugs: {', '.join(dupes)}")
+        return modules
+
+    @property
+    def slugs(self) -> set[str]:
+        """Every known built-in slug."""
+        return {m.slug for m in self.modules}
+
+    def identifiers_excluding(self, disabled_slugs: list[str]) -> list[str]:
+        """FQ identifiers of every built-in whose slug is not in ``disabled_slugs``.
+
+        Order follows the catalog (already alphabetical by slug) so generated
+        whitelists are deterministic and golden-stable.
+        """
+        disabled = set(disabled_slugs)
+        return [m.identifier for m in self.modules if m.slug not in disabled]
+
+
+def load_builtin_catalog(path: Path | None = None) -> BuiltinCatalog:
+    """Load and validate the built-in catalog.
+
+    With ``path=None`` the catalog shipped with the installed package is used;
+    a path overrides it (test fixtures). Mirrors ``catalog.loader.load_catalog``.
+    """
+    yaml_text = _read_yaml_text(path)
+    name = DEFAULT_BUILTIN_CATALOG_NAME
+    try:
+        raw = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as exc:
+        raise BuiltinCatalogLoadError(f"{name} is not valid YAML: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise BuiltinCatalogLoadError(f"{name} top-level must be a mapping.")
+
+    try:
+        return BuiltinCatalog.model_validate(raw)
+    except ValidationError as exc:
+        raise BuiltinCatalogLoadError(
+            f"{DEFAULT_BUILTIN_CATALOG_NAME} failed schema validation:\n{exc}"
+        ) from exc
+
+
+@lru_cache(maxsize=1)
+def default_builtin_catalog() -> BuiltinCatalog:
+    """The built-in catalog shipped with the package, loaded once and cached.
+
+    The data file is immutable package data, so both config validation and the
+    compose engine can share a single memoized read rather than re-parsing YAML
+    on every gateway.
+    """
+    return load_builtin_catalog()
+
+
+def builtin_slugs() -> frozenset[str]:
+    """Slugs of the shipped built-in catalog, for cheap ``disable_builtins`` validation."""
+    return frozenset(default_builtin_catalog().slugs)
+
+
+def validate_disable_slugs(slugs: list[str]) -> None:
+    """Raise ``ValueError`` if any slug is not a known built-in.
+
+    Shared by ``GatewayConfig`` field validation (construction-time) and
+    ``profiles.apply_disable_builtins`` (post-construction mutation, which
+    pydantic does not re-validate), so the wizard/CLI path is guarded too. A
+    typo would otherwise be a silent no-op - the slug just isn't disabled.
+    """
+    known = builtin_slugs()
+    unknown = [s for s in slugs if s not in known]
+    if unknown:
+        raise ValueError(
+            f"unknown built-in module slug(s): {', '.join(unknown)}. "
+            f"Valid slugs are: {', '.join(sorted(known))}"
+        )
+
+
+def _read_yaml_text(path: Path | None) -> str:
+    if path is not None:
+        if not path.is_file():
+            raise BuiltinCatalogLoadError(f"Built-in catalog not found at {path}.")
+        return path.read_text(encoding="utf-8")
+
+    # Installed wheels: force-included as ignition_stack/builtin_modules.yaml.
+    # Editable dev installs: it lives at the repo root next to pyproject.toml.
+    try:
+        bundled = resources.files("ignition_stack").joinpath(DEFAULT_BUILTIN_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_BUILTIN_CATALOG_NAME
+    if not dev_path.is_file():
+        raise BuiltinCatalogLoadError(
+            f"{DEFAULT_BUILTIN_CATALOG_NAME} not found in package data or at {dev_path}."
+        )
+    return dev_path.read_text(encoding="utf-8")