compose2pod 0.2.0__tar.gz → 0.3.0__tar.gz

{compose2pod-0.2.0 → compose2pod-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compose2pod
-Version: 0.2.0
+Version: 0.3.0
 Summary: Convert a Docker Compose file into a script that runs its services as a single Podman pod
 Keywords: podman,docker-compose,compose,pod,ci,testing,containers
 Author: Artur Shiriev
@@ -52,6 +52,16 @@ Built for CI and test environments where you can't use `docker compose` or `podm
 - **No systemd.** Podman healthchecks are normally scheduled by systemd timers. compose2pod gates startup by polling `podman healthcheck run` directly, so `depends_on: service_healthy` works without systemd.
 - **No heavy runtime.** The core is stdlib-only — no dependencies, no compiled wheels — so it installs and runs in minimal Python images.
 
+## Requirements
+
+**Podman >= 6.0.0.** Earlier releases have a bug where a container stopping
+inside a multi-container pod wipes `/etc/hosts` for every container in that
+pod, not just the one that stopped — fixed in 6.0.0. compose2pod's generated
+scripts rely on one shared `--add-host`-populated `/etc/hosts` for the whole
+pod (see `architecture/supported-subset.md`), so a `service_completed_successfully`
+dependency (a container that runs and exits, e.g. a migration step) can wipe
+name resolution for everything started after it on a pre-6.0.0 Podman.
+
 ## Install
 
 ```bash

{compose2pod-0.2.0 → compose2pod-0.3.0}/README.md

@@ -26,6 +26,16 @@ Built for CI and test environments where you can't use `docker compose` or `podm
 - **No systemd.** Podman healthchecks are normally scheduled by systemd timers. compose2pod gates startup by polling `podman healthcheck run` directly, so `depends_on: service_healthy` works without systemd.
 - **No heavy runtime.** The core is stdlib-only — no dependencies, no compiled wheels — so it installs and runs in minimal Python images.
 
+## Requirements
+
+**Podman >= 6.0.0.** Earlier releases have a bug where a container stopping
+inside a multi-container pod wipes `/etc/hosts` for every container in that
+pod, not just the one that stopped — fixed in 6.0.0. compose2pod's generated
+scripts rely on one shared `--add-host`-populated `/etc/hosts` for the whole
+pod (see `architecture/supported-subset.md`), so a `service_completed_successfully`
+dependency (a container that runs and exits, e.g. a migration step) can wipe
+name resolution for everything started after it on a pre-6.0.0 Podman.
+
 ## Install
 
 ```bash

{compose2pod-0.2.0 → compose2pod-0.3.0}/compose2pod/cli.py

@@ -1,44 +1,14 @@
 """Command-line interface: read a compose document and emit the pod script."""
 
 import argparse
-import contextlib
-import json
 import sys
 from pathlib import Path
-from types import ModuleType
-from typing import Any
 
 from compose2pod.emit import POD_NAME_PATTERN, EmitOptions, emit_script, referenced_variables
 from compose2pod.exceptions import UnsupportedComposeError
 from compose2pod.extends import resolve_extends
 from compose2pod.parsing import validate
-
-
-_yaml: ModuleType | None = None
-with contextlib.suppress(ImportError):  # the optional [yaml] extra is not installed
-    import yaml as _yaml
-
-
-def _load_yaml(text: str) -> Any:  # noqa: ANN401 - returns arbitrary parsed compose data
-    if _yaml is None:
-        msg = "YAML input requires the 'yaml' extra: pip install compose2pod[yaml] (or pipe JSON via yq)"
-        raise UnsupportedComposeError(msg)
-    try:
-        return _yaml.safe_load(text)
-    except _yaml.YAMLError as error:
-        msg = f"invalid YAML: {error}"
-        raise UnsupportedComposeError(msg) from error
-
-
-def _read_compose(text: str, fmt: str) -> Any:  # noqa: ANN401 - returns arbitrary parsed compose data
-    if fmt == "json":
-        return json.loads(text)
-    if fmt == "yaml":
-        return _load_yaml(text)
-    try:
-        return json.loads(text)
-    except json.JSONDecodeError:
-        return _load_yaml(text)
+from compose2pod.read import read
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -80,8 +50,8 @@ def main(argv: list[str] | None = None) -> int:
     else:
         text = sys.stdin.read()
     try:
-        compose = _read_compose(text, args.format)
-    except (json.JSONDecodeError, UnsupportedComposeError) as error:
+        compose = read(text, args.format)
+    except UnsupportedComposeError as error:
         sys.stderr.write(f"compose2pod: error: could not parse compose input: {error}\n")
         return 2
     options = EmitOptions(

compose2pod-0.3.0/compose2pod/emit.py

@@ -0,0 +1,402 @@
+"""Render the podman-pod test script for a target service and its dependencies."""
+
+import dataclasses
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+
+from compose2pod import stores
+from compose2pod.exceptions import UnsupportedComposeError
+from compose2pod.graph import depends_on, hostnames, startup_order
+from compose2pod.healthcheck import health_cmd, interval_seconds
+from compose2pod.keys import SERVICE_KEYS, Expand, GuardedEnvFile, Token
+from compose2pod.parsing import validate
+from compose2pod.pod import pod_create_flags
+from compose2pod.resources import deploy_resource_flags
+from compose2pod.shell import to_shell, variable_names
+from compose2pod.values import as_bool
+
+
+HEALTHY_WAIT_BUDGET_SECONDS = 120
+POD_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+
+
+def image_for(svc: dict[str, Any], ci_image: str) -> Token:
+    """Services with a build section run the freshly built CI image."""
+    if "build" in svc:
+        return ci_image
+    return Expand(value=svc["image"])
+
+
+def command_tokens(svc: dict[str, Any]) -> list[Token]:
+    """Service command as argv tokens; compose string form means shell form."""
+    command = svc.get("command")
+    if command is None:
+        return []
+    if isinstance(command, str):
+        return ["/bin/sh", "-c", Expand(value=command)]
+    return [Expand(value=str(token)) for token in command]
+
+
+def entrypoint_tokens(svc: dict[str, Any]) -> list[Token]:
+    """Service entrypoint as argv tokens; compose string form means shell form."""
+    entrypoint = svc.get("entrypoint")
+    if entrypoint is None:
+        return []
+    if isinstance(entrypoint, str):
+        return ["/bin/sh", "-c", Expand(value=entrypoint)]
+    return [Expand(value=str(token)) for token in entrypoint]
+
+
+def _health_flags(healthcheck: dict[str, Any]) -> list[Token]:
+    """Healthcheck flag tokens."""
+    flags: list[Token] = []
+    cmd = health_cmd(healthcheck.get("test"))
+    if cmd is not None:
+        flags += ["--health-cmd", Expand(value=cmd)]
+        # An explicit `null` scalar means unset, not "emit the literal string
+        # 'None'" -- the same treatment `environment`/`volumes`/`command`
+        # give a null value elsewhere in this package, and matching `docker
+        # compose config`, which treats an explicitly-null key as absent.
+        # Keyed off value, not presence, so `timeout: null` and an omitted
+        # `timeout` behave identically.
+        if healthcheck.get("timeout") is not None:
+            flags += ["--health-timeout", str(healthcheck["timeout"])]
+        if healthcheck.get("start_period") is not None:
+            flags += ["--health-start-period", str(healthcheck["start_period"])]
+        if healthcheck.get("retries") is not None:
+            flags += ["--health-retries", str(healthcheck["retries"])]
+    return flags
+
+
+def _env_file_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
+    """--env-file flag tokens.
+
+    `environment` is a SERVICE_KEYS registry key (_map("-e")). A `required: false`
+    long-form entry becomes a run-time-guarded token (see `GuardedEnvFile`) instead
+    of an unconditional flag, so a missing optional file doesn't fail the run.
+    """
+    flags: list[Token] = []
+    env_files = svc.get("env_file") or []
+    if isinstance(env_files, str):
+        env_files = [env_files]
+    for i, entry in enumerate(env_files):
+        if isinstance(entry, str):
+            path, required = entry, True
+        else:
+            path, required = entry["path"], as_bool(entry.get("required", True))
+        resolved = str(Path(project_dir, path))
+        if required:
+            flags += ["--env-file", Expand(value=resolved)]
+        else:
+            flags.append(GuardedEnvFile(var=f"c2p_envfile_{i}", value=resolved))
+    return flags
+
+
+def _nested_mount_parts(vtype: str, options: dict[str, Any]) -> list[str]:
+    """Map a long-form volume entry's validated `bind`/`volume`/`tmpfs` sub-map to `--mount` options."""
+    if vtype == "bind":
+        parts = [f"bind-propagation={options['propagation']}"] if "propagation" in options else []
+        if "selinux" in options:
+            parts.append(f"relabel={'shared' if options['selinux'] == 'z' else 'private'}")
+        return parts
+    if vtype == "volume":
+        return [f"subpath={options['subpath']}"] if "subpath" in options else []
+    # vtype == "tmpfs": the gate validates `type` to one of bind/volume/tmpfs, so no other branch is reachable.
+    parts = [f"tmpfs-size={options['size']}"] if "size" in options else []
+    if "mode" in options:
+        parts.append(f"tmpfs-mode={options['mode']}")
+    return parts
+
+
+def _mount_flag(entry: dict[str, Any], project_dir: str) -> list[Token]:
+    """Render one long-form volume mapping as a `--mount` value."""
+    parts = [f"type={entry['type']}"]
+    source = entry.get("source")
+    if source is not None:
+        if entry["type"] == "bind" and source.startswith("."):
+            source = str(Path(project_dir, source))
+        parts.append(f"source={source}")
+    parts.append(f"target={entry['target']}")
+    if as_bool(entry.get("read_only", False)):
+        parts.append("ro")
+    vtype = entry["type"]
+    parts += _nested_mount_parts(vtype, entry.get(vtype, {}))
+    return ["--mount", Expand(value=",".join(parts))]
+
+
+def _volume_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
+    """-v and --mount flag tokens."""
+    flags: list[Token] = []
+    for volume in svc.get("volumes") or []:
+        if isinstance(volume, dict):
+            flags += _mount_flag(volume, project_dir)
+            continue
+        if ":" not in volume:
+            # Anonymous volume: a bare container path, no host source to translate.
+            flags += ["-v", Expand(value=volume)]
+            continue
+        source, destination = volume.split(":", 1)
+        if source.startswith("."):
+            # Relative bind mount: resolve against project_dir.
+            source = str(Path(project_dir, source))
+        # Absolute bind mount (starts with "/") and named volume (bare
+        # identifier) are both kept as-is — neither is a path to translate.
+        flags += ["-v", Expand(value=f"{source}:{destination}")]
+    return flags
+
+
+def run_flags(name: str, svc: dict[str, Any], pod: str, project_dir: str) -> list[Token]:
+    """Flag tokens (unquoted) for `podman run` of one service."""
+    flags: list[Token] = ["--pod", pod, "--name", f"{pod}-{name}"]
+    flags += _env_file_flags(svc, project_dir)
+    flags += _volume_flags(svc, project_dir)
+    flags += _health_flags(svc.get("healthcheck") or {})
+    for key, spec in SERVICE_KEYS.items():
+        if key in svc:
+            flags += spec.emit(svc[key])
+    flags += stores.flags(svc, pod)
+    flags += deploy_resource_flags(svc)
+    return flags
+
+
+_SCRIPT_HEADER = """\
+#!/bin/sh
+# Generated by compose2pod -- do not edit, regenerate instead.
+set -eu
+
+podman_version=$(podman version --format '{{.Client.Version}}' 2>/dev/null) || podman_version="unknown"
+podman_major=$(echo "$podman_version" | cut -d. -f1)
+case "$podman_major" in
+  ''|*[!0-9]*) ;;  # unparseable -- skip rather than false-positive
+  *) if [ "$podman_major" -lt 6 ]; then
+       echo "warning: podman $podman_version detected; compose2pod requires podman >= 6.0.0" >&2
+       echo "warning: podman < 6.0.0 has a bug where a container stopping in a multi-container" >&2
+       echo "pod wipes /etc/hosts for the whole pod (fixed in 6.0.0) -- name resolution between" >&2
+       echo "services may fail unpredictably" >&2
+     fi ;;
+esac
+
+wait_healthy() {
+  ctr=$1
+  attempts=$2
+  interval=$3
+  i=0
+  while [ "$i" -lt "$attempts" ]; do
+    if podman healthcheck run "$ctr"; then
+      return 0
+    fi
+    i=$((i + 1))
+    sleep "$interval"
+  done
+  echo "wait_healthy: $ctr did not become healthy after $attempts attempts" >&2
+  podman logs "$ctr" >&2 || true
+  return 1
+}
+"""
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class EmitOptions:
+    """Options for emit_script rendering."""
+
+    target: str
+    ci_image: str
+    command: str
+    pod: str
+    project_dir: str
+    artifacts: list[str]
+    allow_exit_codes: list[int]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class PlannedScript:
+    """The rendered pod script and the run-time variables it expands.
+
+    Both are products of a single `_plan` traversal, so they cannot drift.
+    """
+
+    script: str
+    variables: list[str]
+
+
+def _render(tokens: list[Token]) -> str:
+    parts: list[str] = []
+    for token in tokens:
+        if isinstance(token, Expand):
+            parts.append(to_shell(token.value))
+        elif isinstance(token, GuardedEnvFile):
+            parts.append("${" + token.var + ':+"$' + token.var + '"}')
+        else:
+            parts.append(shlex.quote(token))
+    return " ".join(parts)
+
+
+def _collect_vars(tokens: list[Token], names: set[str]) -> None:
+    """Add the run-time variables any `Expand`/`GuardedEnvFile` tokens expand to `names`."""
+    for token in tokens:
+        if isinstance(token, Expand | GuardedEnvFile):
+            names.update(variable_names(token.value))
+
+
+def _env_file_preludes(tokens: list[Token]) -> list[str]:
+    """Build assignment lines for each guarded env_file, set right before the service's `podman run`.
+
+    `${var}` is set to the `--env-file=PATH` flag only if the file exists at run time;
+    `_render` references it inline as `${var:+"$var"}`. The `[ -f ] && ...` list is
+    set -e-safe (the failing test is the left operand of `&&`).
+    """
+    lines: list[str] = []
+    for token in tokens:
+        if isinstance(token, GuardedEnvFile):
+            path = to_shell(token.value)
+            lines.append(f"{token.var}=")
+            lines.append(f"[ -f {path} ] && {token.var}=--env-file={path}")
+    return lines
+
+
+def run_tokens(name: str, services: dict[str, Any], options: EmitOptions) -> list[Token]:
+    svc = services[name]
+    tokens = run_flags(name, svc, options.pod, options.project_dir)
+    entrypoint = entrypoint_tokens(svc)
+    if entrypoint:
+        tokens += ["--entrypoint", entrypoint[0]]
+    tokens.append(image_for(svc, options.ci_image))
+    tokens += entrypoint[1:]
+    if name == options.target and options.command:
+        tokens.extend(shlex.split(options.command))
+    elif not isinstance(svc.get("entrypoint"), str):
+        # A string (shell-form) entrypoint runs via `sh -c`; the service command
+        # is ignored, matching Docker. List/exec form appends the command.
+        tokens.extend(command_tokens(svc))
+    return tokens
+
+
+def _emit_target(lines: list[str], tokens: list[Token], options: EmitOptions) -> None:
+    target_ctr = shlex.quote(f"{options.pod}-{options.target}")
+    lines.append("rc=0")
+    lines.extend(_env_file_preludes(tokens))
+    lines.append(f"podman run {_render(tokens)} || rc=$?")
+    for artifact in options.artifacts:
+        source, destination = artifact.split(":", 1)
+        lines.append(f"podman cp {target_ctr}:{shlex.quote(source)} {shlex.quote(destination)} || true")
+    allowed = "|".join(str(code) for code in [0, *options.allow_exit_codes])
+    lines.append('case "$rc" in')
+    lines.append(f"  {allowed}) ;;")
+    lines.append('  *) echo "target service failed with exit code $rc" >&2')
+    lines.append(
+        "     podman inspect --format "
+        "'OOMKilled={{.State.OOMKilled}} ExitCode={{.State.ExitCode}}' " + target_ctr + " >&2 || true"
+    )
+    lines.append("     podman ps -a --format '{{.Names}} {{.Status}}' >&2 || true")
+    lines.append('     exit "$rc" ;;')
+    lines.append("esac")
+
+
+def _validate_options(options: EmitOptions) -> None:
+    """Check option values emit destructures or interpolates unquoted.
+
+    CLI-unreachable (argparse enforces `artifact` as `str` and
+    `allow_exit_codes` as `int`) but a library caller can pass `EmitOptions`
+    directly: a non-string `artifact` would crash raw on the ':' membership
+    test below, and a non-int `allow_exit_codes` entry is interpolated
+    unquoted into the generated `case "$rc" in ...)` pattern -- shell
+    injection, not just a crash.
+    """
+    for artifact in options.artifacts:
+        if not isinstance(artifact, str) or ":" not in artifact:
+            msg = f"artifact {artifact!r} must be in SRC:DST form"
+            raise UnsupportedComposeError(msg)
+    for code in options.allow_exit_codes:
+        if isinstance(code, bool) or not isinstance(code, int):
+            msg = f"allow_exit_codes entry {code!r} must be an int"
+            raise UnsupportedComposeError(msg)
+
+
+def _plan(compose: dict[str, Any], options: EmitOptions) -> PlannedScript:
+    """Walk the target's dependency closure once, building the script and its variables.
+
+    Every token source is visited a single time and feeds both outputs: each
+    service's `run_tokens` and the `pod_create_flags` render into lines *and*
+    have their `Expand` variables collected, so the script and the variable
+    list cannot disagree about what the script expands at run time.
+
+    `emit_script` and `referenced_variables` are both public entry points that
+    project this traversal, so a library caller can reach either one without
+    ever calling `validate()` first. Validating `compose` here -- and nowhere
+    else -- makes both safe by construction: this is the one place a caller
+    cannot route around. `cli.py` also calls `validate()` itself (to surface
+    warnings), so this repeats that pass; `validate()` only reads `compose`
+    and returns warnings, so the repeat is side-effect-free. The warnings from
+    this pass have no channel to reach a caller here -- `cli.py` surfaces its
+    own copy from its own call -- so they are discarded on purpose.
+    """
+    _validate_options(options)
+    _ = validate(compose)  # re-validate; warnings already surfaced by the caller, if any
+    if not POD_NAME_PATTERN.fullmatch(options.pod):
+        msg = f"invalid pod name {options.pod!r}"
+        raise UnsupportedComposeError(msg)
+    services = compose["services"]
+    order = startup_order(services, options.target)
+    # Only the closure joins the pod, so only the closure is resolvable. A name
+    # pointing at 127.0.0.1 for a service that never runs would turn an honest
+    # resolution failure into a connection-refused.
+    hosts = hostnames({name: services[name] for name in order})
+    completion_gated = {
+        dep
+        for svc in services.values()
+        for dep, condition in depends_on(svc).items()
+        if condition == "service_completed_successfully"
+    }
+    names: set[str] = set()
+
+    lines = [_SCRIPT_HEADER]
+    teardown = f"podman pod rm -f {shlex.quote(options.pod)} >/dev/null 2>&1 || true"
+    store_teardown = stores.teardown_line(compose, order, options.pod)
+    if store_teardown:
+        teardown += f"; {store_teardown}"
+    lines.append(f"trap '{teardown}' EXIT")
+    pod_flags = pod_create_flags(services, order, hosts)
+    _collect_vars(pod_flags, names)
+    pod_create = f"podman pod create --name {shlex.quote(options.pod)}"
+    if pod_flags:
+        pod_create += " " + _render(pod_flags)
+    lines.append(pod_create)
+    lines.extend(stores.create_lines(compose, order, options.pod, options.project_dir))
+    names |= stores.referenced_variables(compose, order, options.project_dir)
+    waited: set[str] = set()
+    for name in order:
+        for dep, condition in depends_on(services[name]).items():
+            if condition == "service_healthy" and dep not in waited:
+                interval = interval_seconds((services[dep].get("healthcheck") or {}).get("interval"))
+                attempts = max(HEALTHY_WAIT_BUDGET_SECONDS // interval, 1)
+                lines.append(f"wait_healthy {shlex.quote(f'{options.pod}-{dep}')} {attempts} {interval}")
+                waited.add(dep)
+        tokens = run_tokens(name, services, options)
+        _collect_vars(tokens, names)
+        if name == options.target:
+            _emit_target(lines, tokens, options)
+        elif name in completion_gated:
+            lines.extend(_env_file_preludes(tokens))
+            lines.append(f"podman run --rm {_render(tokens)}")
+        else:
+            lines.extend(_env_file_preludes(tokens))
+            lines.append(f"podman run -d {_render(tokens)}")
+    return PlannedScript(script="\n".join(lines) + "\n", variables=sorted(names))
+
+
+def emit_script(compose: dict[str, Any], options: EmitOptions) -> str:
+    """Render the full pod test script for `target` and its dependency closure."""
+    return _plan(compose, options).script
+
+
+def referenced_variables(compose: dict[str, Any], options: EmitOptions) -> list[str]:
+    """Variable names the emitted script expands at run time (sorted, unique).
+
+    Projects the same `_plan` traversal `emit_script` renders from, so it counts
+    exactly the values that pass through `to_shell` -- never a `${VAR}` in a
+    field emitted literally, and never the `--command` override (a literal CLI
+    value).
+    """
+    return _plan(compose, options).variables