containerspec 0.1.0__py3-none-any.whl

containerspec/__init__.py

@@ -0,0 +1,116 @@
+"""ContainerSpec — fluent, content-hashed image builder for Docker, Firecracker, and OCI.
+
+Mirrors Modal's Image API surface but targets any Docker daemon, BuildKit instance,
+or Buildah (daemonless) for producing Docker images, Firecracker rootfs ext4 images,
+and OCI tarballs. Every method returns a new frozen ``ImageSpec``.
+
+Convenience methods (``nvm_install``, ``npm_install``, ``brew_install``, ``rust_install``,
+``cargo_install``, ``uvx_install``) generate the correct bootstrap + install + PATH setup.
+For custom tooling, use ``run_commands()`` directly.
+
+``docker`` is a lazy import inside ``build()`` — ``to_dockerfile()``,
+``content_hash()``, and ``tag()`` work without Docker installed.
+"""
+
+from __future__ import annotations
+
+from containerspec.backends import (
+    BuildahBackend,
+    BuildBackend,
+    BuildError,
+    BuildKitBackend,
+    DockerBackend,
+)
+from containerspec.layers import (
+    AddPython,
+    ApkInstall,
+    AptInstall,
+    BrewInstall,
+    CargoInstall,
+    Chown,
+    Cmd,
+    Copy,
+    CopyFromStage,
+    DnfInstall,
+    Entrypoint,
+    Env,
+    Expose,
+    GemInstall,
+    GoInstall,
+    Layer,
+    NpmInstall,
+    NvmInstall,
+    PacmanInstall,
+    PipInstall,
+    PnpmInstall,
+    RunCommands,
+    RustInstall,
+    User,
+    UvPipInstall,
+    UvxInstall,
+    Volume,
+    Workdir,
+    YarnInstall,
+    ZypperInstall,
+)
+from containerspec.rootfs import MissingToolError
+from containerspec.spec import ImageSpec, StageSpec
+from containerspec.targets import (
+    BuildTarget,
+    BuiltImage,
+    DockerTarget,
+    FirecrackerRootfs,
+    FirecrackerRootfsTarget,
+    OciArtifact,
+    OciTarget,
+)
+
+__all__ = [
+    "AddPython",
+    "ApkInstall",
+    "AptInstall",
+    "BrewInstall",
+    "BuildBackend",
+    "BuildError",
+    "BuildKitBackend",
+    "BuildTarget",
+    "BuildahBackend",
+    "BuiltImage",
+    "CargoInstall",
+    "Chown",
+    "Cmd",
+    "Copy",
+    "CopyFromStage",
+    "DnfInstall",
+    "DockerBackend",
+    "DockerTarget",
+    "Entrypoint",
+    "Env",
+    "Expose",
+    "FirecrackerRootfs",
+    "FirecrackerRootfsTarget",
+    "GemInstall",
+    "GoInstall",
+    "ImageSpec",
+    "Layer",
+    "MissingToolError",
+    "NpmInstall",
+    "NvmInstall",
+    "OciArtifact",
+    "OciTarget",
+    "PacmanInstall",
+    "PipInstall",
+    "PnpmInstall",
+    "RunCommands",
+    "RustInstall",
+    "StageSpec",
+    "User",
+    "UvPipInstall",
+    "UvxInstall",
+    "Volume",
+    "Workdir",
+    "YarnInstall",
+    "ZypperInstall",
+]
+
+__version__ = "0.1.0"

containerspec/backends.py

@@ -0,0 +1,247 @@
+"""Build backends — BuildKitBackend (docker buildx), BuildahBackend (daemonless), DockerBackend (docker-py)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+logger = logging.getLogger("containerspec")
+
+
+class BuildError(RuntimeError):
+    """Raised when a build subprocess fails. Includes stderr and command for diagnostics."""
+
+    def __init__(
+        self, message: str, *, cmd: list[str] | None = None, stderr: str | None = None
+    ) -> None:
+        self.cmd = cmd
+        self.stderr = stderr
+        parts = [message]
+        if cmd:
+            parts.append(f"Command: {' '.join(cmd)}")
+        if stderr:
+            parts.append(f"stderr:\n{stderr}")
+        super().__init__("\n".join(parts))
+
+
+@runtime_checkable
+class BuildBackend(Protocol):
+    """A build execution backend."""
+
+    async def solve_and_export(
+        self,
+        *,
+        dockerfile: str,
+        tag: str,
+        output_type: str,
+        output_path: str | None,
+        labels: dict[str, str],
+        pull: bool,
+    ) -> None: ...
+
+
+def _write_dockerfile_temp(dockerfile: str) -> str:
+    """Write Dockerfile to a temp file. Returns the path. Caller must clean up."""
+    fd, path = tempfile.mkstemp(suffix="Dockerfile", prefix="containerspec-")
+    with open(fd, "w") as f:
+        f.write(dockerfile)
+    logger.debug("containerspec.dockerfile.temp", extra={"path": path})
+    return path
+
+
+async def _run_command(cmd: list[str], *, label: str) -> tuple[int, bytes, bytes]:
+    """Run a command, log it, return (rc, stdout, stderr)."""
+    logger.info(f"containerspec.{label}.run", extra={"cmd": cmd})
+    proc = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await proc.communicate()
+    if proc.returncode != 0:
+        err = stderr.decode() if stderr else "(no stderr)"
+        logger.error(f"containerspec.{label}.failed", extra={"rc": proc.returncode, "stderr": err})
+        raise BuildError(
+            f"{label} failed with exit code {proc.returncode}",
+            cmd=cmd,
+            stderr=err,
+        )
+    logger.info(f"containerspec.{label}.complete")
+    return proc.returncode, stdout, stderr
+
+
+@dataclass(frozen=True)
+class BuildKitBackend:
+    """Build via ``docker buildx build`` CLI. Supports all output types.
+
+    Dockerfile is written to a temp file and passed via ``-f`` — more robust
+    than stdin piping, and the temp file is preserved on failure for debugging.
+    """
+
+    url: str | None = None
+    builder: str | None = None
+
+    async def solve_and_export(
+        self,
+        *,
+        dockerfile: str,
+        tag: str,
+        output_type: str,
+        output_path: str | None,
+        labels: dict[str, str],
+        pull: bool,
+    ) -> None:
+        dockerfile_path = _write_dockerfile_temp(dockerfile)
+        try:
+            cmd: list[str] = ["docker", "buildx", "build"]
+            if self.builder:
+                cmd.extend(["--builder", self.builder])
+            if output_path:
+                output_val = f"type={output_type},dest={output_path}"
+            else:
+                output_val = f"type={output_type}"
+            cmd.extend(["--output", output_val, "--tag", tag, "-f", dockerfile_path])
+            if pull:
+                cmd.append("--pull")
+            for k, v in labels.items():
+                cmd.extend(["--label", f"{k}={v}"])
+            cmd.append(".")
+            await _run_command(cmd, label="buildx")
+        finally:
+            Path(dockerfile_path).unlink(missing_ok=True)
+
+
+@dataclass(frozen=True)
+class BuildahBackend:
+    """Build via ``buildah bud`` CLI. Daemonless — no Docker daemon needed.
+
+    Default for FirecrackerRootfsTarget and OciTarget. Does NOT support
+    ``output_type="docker"`` (use BuildKitBackend or DockerBackend for that).
+    Linux-only — ``MissingToolError`` if buildah is not on PATH.
+    """
+
+    async def solve_and_export(
+        self,
+        *,
+        dockerfile: str,
+        tag: str,
+        output_type: str,
+        output_path: str | None,
+        labels: dict[str, str],
+        pull: bool,
+    ) -> None:
+        from containerspec.rootfs import check_buildah
+
+        check_buildah()
+
+        if output_type == "docker":
+            raise BuildError(
+                "BuildahBackend does not support output_type='docker'. "
+                "Use BuildKitBackend or DockerBackend for Docker targets."
+            )
+
+        dockerfile_path = _write_dockerfile_temp(dockerfile)
+        try:
+            build_cmd: list[str] = ["buildah", "bud", "-f", dockerfile_path, "-t", tag]
+            if pull:
+                build_cmd.append("--pull")
+            for k, v in labels.items():
+                build_cmd.extend(["--label", f"{k}={v}"])
+            build_cmd.append(".")
+            await _run_command(build_cmd, label="buildah.bud")
+
+            if output_type == "oci" and output_path:
+                push_cmd = ["buildah", "push", "-f", "oci-archive", tag, output_path]
+                await _run_command(push_cmd, label="buildah.push.oci")
+            elif output_type == "local" and output_path:
+                await self._export_filesystem(tag=tag, dest=output_path)
+        finally:
+            Path(dockerfile_path).unlink(missing_ok=True)
+
+    async def _export_filesystem(self, *, tag: str, dest: str) -> None:
+        """Export the working container's filesystem to dest using buildah mount."""
+        from_cmd = ["buildah", "from", tag]
+        _, stdout, _ = await _run_command(from_cmd, label="buildah.from")
+        container_name = stdout.decode().strip()
+
+        try:
+            mount_cmd = ["buildah", "mount", container_name]
+            _, stdout, _ = await _run_command(mount_cmd, label="buildah.mount")
+            mountpoint = stdout.decode().strip()
+
+            copy_cmd = ["cp", "-a", f"{mountpoint}/.", dest + "/"]
+            await _run_command(copy_cmd, label="buildah.copy")
+
+            umount_cmd = ["buildah", "umount", container_name]
+            await _run_command(umount_cmd, label="buildah.umount")
+        finally:
+            rm_cmd = ["buildah", "rm", container_name]
+            await _run_command(rm_cmd, label="buildah.rm")
+
+
+@dataclass
+class DockerBackend:
+    """Build via docker-py. Docker target only (fallback when buildx unavailable)."""
+
+    client: Any = None
+
+    async def solve_and_export(
+        self,
+        *,
+        dockerfile: str,
+        tag: str,
+        output_type: str,
+        output_path: str | None,
+        labels: dict[str, str],
+        pull: bool,
+    ) -> None:
+        if output_type != "docker":
+            raise BuildError(
+                f"DockerBackend does not support output_type='{output_type}'. "
+                "Use BuildKitBackend or BuildahBackend for non-Docker targets."
+            )
+        import io
+
+        if self.client is None:
+            import docker
+
+            self.client = docker.from_env()
+        logger.info("containerspec.docker.build", extra={"tag": tag})
+        await asyncio.to_thread(
+            self.client.images.build,
+            fileobj=io.BytesIO(dockerfile.encode()),
+            tag=tag,
+            pull=pull,
+            rm=True,
+            labels=labels,
+        )
+        logger.info("containerspec.docker.complete", extra={"tag": tag})
+
+
+def auto_detect_backend(*, target: Any = None) -> BuildBackend:
+    """Pick the best backend for the given target.
+
+    - DockerTarget: BuildKitBackend if buildx is available, else DockerBackend.
+    - FirecrackerRootfsTarget / OciTarget: BuildahBackend if available (daemonless),
+      else BuildKitBackend if buildx is available, else DockerBackend (will error
+      for non-Docker output types).
+    """
+    from containerspec.targets import DockerTarget
+
+    is_docker_target = isinstance(target, DockerTarget) if target else True
+
+    if is_docker_target:
+        if shutil.which("docker") is not None:
+            return BuildKitBackend()
+        return DockerBackend()
+
+    if shutil.which("buildah") is not None:
+        return BuildahBackend()
+    if shutil.which("docker") is not None:
+        return BuildKitBackend()
+    return DockerBackend()

containerspec/distros.py

@@ -0,0 +1,89 @@
+"""Distro profiles — data-driven distro-specific command configuration.
+
+Instead of branching in renderer functions, each distro declares its
+user-creation commands, package-update commands, and non-interactive env.
+Adding a new distro is a data entry, not code changes across renderers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DistroProfile:
+    """Distro-specific command templates for rendering."""
+
+    group_add: str
+    user_add: str
+    package_update: str
+    noninteractive_prefix: str
+
+
+DISTRO_PROFILES: dict[str, DistroProfile] = {
+    "debian": DistroProfile(
+        group_add="groupadd -g {gid} {name}",
+        user_add="useradd -u {uid} -g {gid} -m -d /home/{name} {name}",
+        package_update=(
+            "DEBIAN_FRONTEND=noninteractive apt-get update && "
+            "apt-get dist-upgrade -y --no-install-recommends && "
+            "apt-get clean && rm -rf /var/lib/apt/lists/*"
+        ),
+        noninteractive_prefix="DEBIAN_FRONTEND=noninteractive",
+    ),
+    "alpine": DistroProfile(
+        group_add="addgroup -g {gid} {name}",
+        user_add="adduser -u {uid} -G {name} -D -h /home/{name} {name}",
+        package_update="apk update && apk upgrade --no-cache",
+        noninteractive_prefix="",
+    ),
+    "rhel": DistroProfile(
+        group_add="groupadd -g {gid} {name}",
+        user_add="useradd -u {uid} -g {gid} -m -d /home/{name} {name}",
+        package_update="dnf upgrade -y && dnf clean all",
+        noninteractive_prefix="",
+    ),
+    "fedora": DistroProfile(
+        group_add="groupadd -g {gid} {name}",
+        user_add="useradd -u {uid} -g {gid} -m -d /home/{name} {name}",
+        package_update="dnf upgrade -y && dnf clean all",
+        noninteractive_prefix="",
+    ),
+    "arch": DistroProfile(
+        group_add="groupadd -g {gid} {name}",
+        user_add="useradd -u {uid} -g {gid} -m -d /home/{name} {name}",
+        package_update="pacman -Syu --noconfirm",
+        noninteractive_prefix="",
+    ),
+    "opensuse": DistroProfile(
+        group_add="groupadd -g {gid} {name}",
+        user_add="useradd -u {uid} -g {gid} -m -d /home/{name} {name}",
+        package_update="zypper update -y",
+        noninteractive_prefix="",
+    ),
+    "busybox": DistroProfile(
+        group_add="addgroup -g {gid} {name}",
+        user_add="adduser -u {uid} -G {name} -D -h /home/{name} {name}",
+        package_update="apk update && apk upgrade --no-cache",
+        noninteractive_prefix="",
+    ),
+}
+
+
+def get_profile(distro: str | None) -> DistroProfile:
+    """Get the distro profile, falling back to debian (the most common base)."""
+    if distro and distro in DISTRO_PROFILES:
+        return DISTRO_PROFILES[distro]
+    return DISTRO_PROFILES["debian"]
+
+
+def distro_from_pm(pm: str | None) -> str | None:
+    """Infer distro from package manager used."""
+    pm_to_distro = {
+        "apt": "debian",
+        "apk": "alpine",
+        "dnf": "rhel",
+        "pacman": "arch",
+        "zypper": "opensuse",
+    }
+    return pm_to_distro.get(pm) if pm else None

containerspec/layers.py

@@ -0,0 +1,259 @@
+"""Layer types for ImageSpec — frozen dataclasses, discriminated union."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Layer:
+    """Base type for all image layers."""
+
+
+@dataclass(frozen=True)
+class AddPython(Layer):
+    version: str
+
+
+@dataclass(frozen=True)
+class AptInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ApkInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class DnfInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PacmanInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ZypperInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class UvPipInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PipInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Env(Layer):
+    vars: Mapping[str, str]
+
+
+@dataclass(frozen=True)
+class RunCommands(Layer):
+    commands: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Workdir(Layer):
+    path: str
+
+
+@dataclass(frozen=True)
+class Chown(Layer):
+    path: str
+    uid: int | None = None
+    gid: int | None = None
+
+
+@dataclass(frozen=True)
+class User(Layer):
+    uid: int
+    gid: int
+    name: str
+    alpine: bool = False
+
+
+@dataclass(frozen=True)
+class Entrypoint(Layer):
+    commands: tuple[str, ...] | None
+
+
+@dataclass(frozen=True)
+class Expose(Layer):
+    ports: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Cmd(Layer):
+    commands: tuple[str, ...] | None
+
+
+@dataclass(frozen=True)
+class Volume(Layer):
+    paths: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Copy(Layer):
+    src: str
+    dest: str
+    content_hash: str = ""
+
+
+@dataclass(frozen=True)
+class NvmInstall(Layer):
+    version: str
+
+
+@dataclass(frozen=True)
+class NpmInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PnpmInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BrewInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RustInstall(Layer):
+    pass
+
+
+@dataclass(frozen=True)
+class CargoInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class UvxInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class YarnInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class GemInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class GoInstall(Layer):
+    packages: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class CopyFromStage(Layer):
+    stage_name: str
+    stage_hash: str
+    src: str
+    dest: str
+
+
+def frozen_mapping(vars: Mapping[str, str]) -> Mapping[str, str]:
+    """Wrap a dict in MappingProxyType for immutability."""
+    return MappingProxyType(dict(vars))
+
+
+def layer_payload(layer: Layer) -> dict[str, Any]:
+    """Serialize a layer to its canonical dict for hashing."""
+    if isinstance(layer, AddPython):
+        return {"type": "add_python", "version": layer.version}
+    if isinstance(layer, AptInstall):
+        return {"type": "apt_install", "packages": list(layer.packages)}
+    if isinstance(layer, ApkInstall):
+        return {"type": "apk_install", "packages": list(layer.packages)}
+    if isinstance(layer, DnfInstall):
+        return {"type": "dnf_install", "packages": list(layer.packages)}
+    if isinstance(layer, PacmanInstall):
+        return {"type": "pacman_install", "packages": list(layer.packages)}
+    if isinstance(layer, ZypperInstall):
+        return {"type": "zypper_install", "packages": list(layer.packages)}
+    if isinstance(layer, UvPipInstall):
+        return {"type": "uv_pip_install", "packages": list(layer.packages)}
+    if isinstance(layer, PipInstall):
+        return {"type": "pip_install", "packages": list(layer.packages)}
+    if isinstance(layer, Env):
+        return {"type": "env", "vars": dict(layer.vars)}
+    if isinstance(layer, RunCommands):
+        return {"type": "run_commands", "commands": list(layer.commands)}
+    if isinstance(layer, Workdir):
+        return {"type": "workdir", "path": layer.path}
+    if isinstance(layer, Chown):
+        return {"type": "chown", "path": layer.path, "uid": layer.uid, "gid": layer.gid}
+    if isinstance(layer, User):
+        return {
+            "type": "user",
+            "uid": layer.uid,
+            "gid": layer.gid,
+            "name": layer.name,
+            "alpine": layer.alpine,
+        }
+    if isinstance(layer, Entrypoint):
+        return {
+            "type": "entrypoint",
+            "commands": list(layer.commands) if layer.commands is not None else None,
+        }
+    if isinstance(layer, Expose):
+        return {"type": "expose", "ports": list(layer.ports)}
+    if isinstance(layer, Cmd):
+        return {
+            "type": "cmd",
+            "commands": list(layer.commands) if layer.commands is not None else None,
+        }
+    if isinstance(layer, Volume):
+        return {"type": "volume", "paths": list(layer.paths)}
+    if isinstance(layer, Copy):
+        return {
+            "type": "copy",
+            "src": layer.src,
+            "dest": layer.dest,
+            "content_hash": layer.content_hash,
+        }
+    if isinstance(layer, NvmInstall):
+        return {"type": "nvm_install", "version": layer.version}
+    if isinstance(layer, NpmInstall):
+        return {"type": "npm_install", "packages": list(layer.packages)}
+    if isinstance(layer, PnpmInstall):
+        return {"type": "pnpm_install", "packages": list(layer.packages)}
+    if isinstance(layer, BrewInstall):
+        return {"type": "brew_install", "packages": list(layer.packages)}
+    if isinstance(layer, RustInstall):
+        return {"type": "rust_install"}
+    if isinstance(layer, CargoInstall):
+        return {"type": "cargo_install", "packages": list(layer.packages)}
+    if isinstance(layer, UvxInstall):
+        return {"type": "uvx_install", "packages": list(layer.packages)}
+    if isinstance(layer, YarnInstall):
+        return {"type": "yarn_install", "packages": list(layer.packages)}
+    if isinstance(layer, GemInstall):
+        return {"type": "gem_install", "packages": list(layer.packages)}
+    if isinstance(layer, GoInstall):
+        return {"type": "go_install", "packages": list(layer.packages)}
+    if isinstance(layer, CopyFromStage):
+        return {
+            "type": "copy_from_stage",
+            "stage_name": layer.stage_name,
+            "stage_hash": layer.stage_hash,
+            "src": layer.src,
+            "dest": layer.dest,
+        }
+    raise TypeError(f"Unknown layer type: {type(layer).__name__}")