codecraftai-provisioning 1.3.0__py3-none-any.whl

ccai/provisioning/aspects/provisioningaspects.py

@@ -0,0 +1,46 @@
+"""
+    .. module:: provisioningaspects
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: ProvisioningAspects — behaviour bundle for provisioning calls.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Optional
+
+
+class ProvisioningAspects:
+    """
+        Aspect bundle controlling provisioning behaviour.
+
+        Following the project Aspects pattern: callers pass behaviour as a
+        single parameter rather than via decorators.
+    """
+
+    def __init__(self, *, dry_run: bool = False, confirm: bool = False,
+                 runid: Optional[str] = None,
+                 verify_timeout: float = 600.0,
+                 verify_interval: float = 10.0,
+                 lock_timeout_seconds: float = 30.0) -> None:
+        """
+            Construct a ProvisioningAspects bundle.
+
+            :param dry_run: When True, the engine halts at the end of PLAN.
+            :param confirm: When True, destroy is permitted.
+            :param runid: Optional run identifier for state-persistence.
+            :param verify_timeout: Total timeout for the VERIFY stage.
+            :param verify_interval: Polling interval for VERIFY.
+            :param lock_timeout_seconds: Index-file lock wait timeout.
+        """
+        self.dry_run: bool = dry_run
+        self.confirm: bool = confirm
+        self.runid: Optional[str] = runid
+        self.verify_timeout: float = verify_timeout
+        self.verify_interval: float = verify_interval
+        self.lock_timeout_seconds: float = lock_timeout_seconds
+        return

ccai/provisioning/cloudinit/bootstraprenderer.py

@@ -0,0 +1,139 @@
+"""
+    .. module:: bootstraprenderer
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Composes every first-boot fragment a CloudInstance declares
+               into one cloud-init document.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+
+    Venue renderers historically checked ``instance.vpn_join`` and called
+    :func:`render_cloud_init` directly.  As more bootstrap concerns arrive
+    (Python environments today), that per-venue branching would have to be
+    repeated in every venue.  This module is the single place that knows
+    which instance slots produce cloud-init fragments and in what order;
+    venues call :func:`render_instance_cloud_init` and only decide how to
+    ship the resulting document (base64, verbatim, seed ISO, ...).
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from ccai.provisioning.cloudinit.bootstrapsecrets import BootstrapSecrets
+from ccai.provisioning.cloudinit.cloudinitmerge import merge_cloud_init_fragments
+from ccai.provisioning.cloudinit.pythonenvcloudinitrenderer import (
+    render_python_env_cloud_init
+)
+from ccai.provisioning.cloudinit.vpncloudinitrenderer import render_cloud_init
+from ccai.provisioning.model.cloud.cloudinstance import CloudInstance
+
+
+CLOUD_CONFIG_HEADER = "#cloud-config"
+
+
+def render_instance_cloud_init(*, instance: CloudInstance,
+                               authkey: Optional[str] = None,
+                               rendered_hostname: Optional[str] = None,
+                               secrets: Optional[BootstrapSecrets] = None
+                               ) -> Optional[Dict[str, Any]]:
+    """
+        Render and merge every cloud-init fragment the instance declares.
+
+        Order: VPN join first (so the overlay is up before anything that
+        might need a private index), then Python environments.  A raw
+        ``user_data_script`` is appended as a final ``runcmd`` entry so it
+        runs after the managed bootstrap.
+
+        :param instance: The neutral CloudInstance.
+        :param authkey: Minted VPN auth-key; required when ``vpn_join`` is
+                        set (an empty string is substituted otherwise).
+        :param rendered_hostname: Hostname rendered from the join spec
+                                  template; defaults to the instance name.
+        :param secrets: Optional resolved :class:`BootstrapSecrets`; when
+                        ``None`` the container bound by the engine for the
+                        current apply is used.
+
+        :returns: The merged fragment, or ``None`` when the instance
+                  declares no bootstrap content at all.
+    """
+    fragments: List[Optional[Dict[str, Any]]] = []
+
+    if instance.vpn_join is not None:
+        effective_hostname = rendered_hostname
+        if effective_hostname is None or len(effective_hostname) == 0:
+            effective_hostname = instance.name
+        effective_authkey = authkey if authkey is not None else ""
+        fragments.append(render_cloud_init(
+            spec=instance.vpn_join,
+            authkey=effective_authkey,
+            rendered_hostname=effective_hostname,
+            image_family=instance.image.family,
+        ))
+
+    python_environments = instance.python_environments
+    if python_environments is not None and len(python_environments) > 0:
+        fragments.append(render_python_env_cloud_init(
+            specs=python_environments,
+            image_family=instance.image.family,
+            secrets=secrets,
+        ))
+
+    raw_script = instance.user_data_script
+    if len(fragments) == 0:
+        rtnval: Optional[Dict[str, Any]] = None
+        return rtnval
+
+    merged = merge_cloud_init_fragments(*fragments)
+    if raw_script is not None and len(raw_script) > 0:
+        runcmd: List[Any] = list(merged.get("runcmd", []))
+        runcmd.append(["sh", "-c", raw_script])
+        merged["runcmd"] = runcmd
+
+    rtnval = merged
+    return rtnval
+
+
+def render_instance_user_data(*, instance: CloudInstance,
+                              authkey: Optional[str] = None,
+                              rendered_hostname: Optional[str] = None,
+                              secrets: Optional[BootstrapSecrets] = None
+                              ) -> Optional[str]:
+    """
+        Render the complete ``#cloud-config`` document for an instance.
+
+        :param instance: The neutral CloudInstance.
+        :param authkey: Minted VPN auth-key when ``vpn_join`` is set.
+        :param rendered_hostname: Hostname for the join spec.
+        :param secrets: Optional resolved :class:`BootstrapSecrets`.
+
+        :returns: The YAML document with the ``#cloud-config`` header; the
+                  raw ``user_data_script`` verbatim when that is the only
+                  bootstrap content; ``None`` when there is none.
+    """
+    fragment = render_instance_cloud_init(
+        instance=instance, authkey=authkey, rendered_hostname=rendered_hostname,
+        secrets=secrets,
+    )
+    if fragment is None:
+        raw_script = instance.user_data_script
+        if raw_script is None or len(raw_script) == 0:
+            rtnval: Optional[str] = None
+            return rtnval
+        rtnval = raw_script
+        return rtnval
+
+    body = yaml.safe_dump(fragment, default_flow_style=False, sort_keys=False)
+    rtnval = "{}\n{}".format(CLOUD_CONFIG_HEADER, body)
+    return rtnval
+
+
+__all__ = [
+    "CLOUD_CONFIG_HEADER",
+    "render_instance_cloud_init",
+    "render_instance_user_data",
+]

ccai/provisioning/cloudinit/bootstrapsecrets.py

@@ -0,0 +1,128 @@
+"""
+    .. module:: bootstrapsecrets
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Per-run container for secrets the first-boot renderers need,
+               resolved once by the engine and bound for the apply stages.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+
+    Specs never carry secrets.  ``PythonEnvironmentSpec.index_credential``
+    names a credential-vault entry; the engine resolves every such name
+    during LOAD_VALIDATE into a :class:`BootstrapSecrets` and binds it for
+    the duration of the apply stages with :func:`bind_bootstrap_secrets`.
+    Renderers read :func:`current_bootstrap_secrets` when a caller does not
+    hand them a container explicitly, so the twenty venue user-data paths
+    need no new plumbing and no venue ever touches a credential vault.
+
+    The binding is a :class:`contextvars.ContextVar`, which is per-thread
+    and per-task, so two engines applying concurrently in one process do
+    not see each other's secrets.
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+import contextlib
+import contextvars
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, Optional
+
+
+@dataclass(frozen=True)
+class IndexCredential:
+    """
+        Credentials for a package index.
+
+        :param username: HTTP basic-auth username (``__token__`` for
+                         token-style indexes such as PyPI and most private
+                         mirrors).
+        :param secret: The password or token.
+    """
+    username: str
+    secret: str
+
+    def __repr__(self) -> str:
+        """
+            Never let the secret into a log line or an exception message.
+        """
+        rtnval = "IndexCredential(username={!r}, secret='***')".format(self.username)
+        return rtnval
+
+
+@dataclass
+class BootstrapSecrets:
+    """
+        Resolved secrets for one provisioning run.
+
+        :param index_credentials: Map of credential-vault reference (the
+                                  value of ``PythonEnvironmentSpec.
+                                  index_credential``) to the resolved
+                                  :class:`IndexCredential`.
+    """
+    index_credentials: Dict[str, IndexCredential] = field(default_factory=dict)
+
+    def credential_for(self, *, spec: Any) -> Optional[IndexCredential]:
+        """
+            Look up the credential a spec names.
+
+            :param spec: A ``PythonEnvironmentSpec`` (anything with an
+                         ``index_credential`` attribute).
+
+            :returns: The :class:`IndexCredential`, or ``None`` when the spec
+                      names no credential or the name is not resolved here.
+        """
+        reference = getattr(spec, "index_credential", None)
+        if reference is None:
+            rtnval: Optional[IndexCredential] = None
+            return rtnval
+        rtnval = self.index_credentials.get(reference, None)
+        return rtnval
+
+    def __repr__(self) -> str:
+        rtnval = "BootstrapSecrets(index_credentials={})".format(
+            sorted(self.index_credentials.keys())
+        )
+        return rtnval
+
+
+_CURRENT: contextvars.ContextVar = contextvars.ContextVar(
+    "ccai_provisioning_bootstrap_secrets", default=None
+)
+
+
+def current_bootstrap_secrets() -> Optional[BootstrapSecrets]:
+    """
+        The :class:`BootstrapSecrets` bound for the calling context, or
+        ``None`` outside an engine apply.
+
+        :returns: The bound container or ``None``.
+    """
+    rtnval = _CURRENT.get()
+    return rtnval
+
+
+@contextlib.contextmanager
+def bind_bootstrap_secrets(secrets: Optional[BootstrapSecrets]) -> Iterator[None]:
+    """
+        Bind ``secrets`` as the current container for the duration of the
+        ``with`` block, restoring the previous binding afterwards.
+
+        :param secrets: The container to bind (``None`` clears the binding).
+    """
+    token = _CURRENT.set(secrets)
+    try:
+        yield
+    finally:
+        _CURRENT.reset(token)
+    return
+
+
+__all__ = [
+    "BootstrapSecrets",
+    "IndexCredential",
+    "bind_bootstrap_secrets",
+    "current_bootstrap_secrets",
+]

ccai/provisioning/cloudinit/cloudinitmerge.py

@@ -0,0 +1,68 @@
+"""
+    .. module:: cloudinitmerge
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Merge helper for venue-neutral cloud-init fragments.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+import copy
+import os
+
+from typing import Any, Dict, Optional
+
+from ccai.provisioning.cloudinit.cloudinitrenderererror import (
+    CloudInitRendererError
+)
+
+
+def merge_cloud_init_fragments(*fragments: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+        Merge cloud-init fragments produced by the shared renderers.
+
+        List-valued keys (``write_files``, ``runcmd``, ``packages``, ...)
+        are concatenated in argument order, so bootstrap ordering follows
+        the order the fragments are passed.  Scalar keys must agree
+        across fragments; a conflict raises rather than silently picking
+        a winner.  ``None`` fragments are skipped.
+
+        :param fragments: Fragment dicts (or ``None``).
+
+        :returns: A new merged dict; inputs are not mutated.
+
+        :raises: CloudInitRendererError
+    """
+    rtnval: Dict[str, Any] = {}
+
+    for fragment in fragments:
+        if fragment is None:
+            continue
+        for key, value in fragment.items():
+            if key not in rtnval:
+                rtnval[key] = copy.deepcopy(value)
+                continue
+
+            existing = rtnval[key]
+            if isinstance(existing, list) and isinstance(value, list):
+                existing.extend(copy.deepcopy(value))
+                continue
+
+            if existing == value:
+                continue
+
+            err_msg_lines = ["Conflicting scalar value while merging cloud-init fragments."]
+            err_msg_lines.append("KEY: {!r}".format(key))
+            err_msg_lines.append("EXISTING: {!r}".format(existing))
+            err_msg_lines.append("INCOMING: {!r}".format(value))
+            err_msg = os.linesep.join(err_msg_lines)
+            raise CloudInitRendererError(err_msg)
+
+    return rtnval
+
+
+__all__ = ["merge_cloud_init_fragments"]

ccai/provisioning/cloudinit/cloudinitrenderererror.py

@@ -0,0 +1,18 @@
+"""
+    .. module:: cloudinitrenderererror
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Exception type for cloud-init renderer failures.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+class CloudInitRendererError(ValueError):
+    """
+        Raised when an unsupported image family is requested or the renderer
+        cannot produce a valid payload.
+    """