sonata-tasks 0.6.1__py3-none-any.whl

sonata_tasks/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable tasks for the Sonata workflow engine."""
+
+from sonata_tasks.core.command import CommandTask
+from sonata_tasks.execution.models import CommandOptions, CommandTaskSpec, TaskResult
+
+__all__ = ["CommandOptions", "CommandTask", "CommandTaskSpec", "TaskResult"]

sonata_tasks/ansible.py

@@ -0,0 +1,83 @@
+"""Run an Ansible playbook as a command task."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from sonata_tasks.command import CommandTask
+from sonata_tasks.execution.models import CommandOptions
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+def build_ansible_argv(
+    *,
+    playbook: Path,
+    inventory: str,
+    user: str,
+    private_key_path: Path | None = None,
+    extra_vars: Mapping[str, str] | None = None,
+) -> tuple[str, ...]:
+    """Build the ``ansible-playbook`` argv for a playbook run.
+
+    ``private_key_path`` becomes ``--private-key`` and each ``extra_vars`` entry
+    becomes an ``-e key=value`` pair. The playbook is appended last as an
+    absolute path, so the command does not depend on the caller's working
+    directory.
+    """
+    argv = ["ansible-playbook", "-i", inventory, "-u", user]
+    if private_key_path is not None:
+        argv.extend(("--private-key", str(private_key_path)))
+    for key, value in (extra_vars or {}).items():
+        argv.extend(("-e", f"{key}={value}"))
+    argv.append(str(Path(playbook).absolute()))
+    return tuple(argv)
+
+
+class AnsiblePlaybookTask(CommandTask):
+    """Run a playbook against an inventory, optionally under a custom config.
+
+    Command building is left to :func:`build_ansible_argv`; this class only
+    folds ``ansible_config`` into the environment as ``ANSIBLE_CONFIG`` before
+    handing everything to :class:`~sonata_tasks.command.CommandTask`.
+    """
+
+    def __init__(
+        self,
+        *,
+        playbook: Path,
+        inventory: str,
+        user: str,
+        executor: CommandTaskExecutor,
+        role: str = "host",
+        private_key_path: Path | None = None,
+        extra_vars: Mapping[str, str] | None = None,
+        ansible_config: Path | None = None,
+        options: CommandOptions | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Configure the playbook run.
+
+        ``ansible_config`` is exported as ``ANSIBLE_CONFIG`` on top of any
+        environment already set in ``options``. ``title`` defaults to the
+        playbook's file name, and ``role`` selects the executor binding.
+        """
+        current = options or CommandOptions()
+        if ansible_config is not None:
+            current = replace(
+                current, env={**current.env, "ANSIBLE_CONFIG": str(ansible_config)}
+            )
+        super().__init__(
+            title=title or f"Run Ansible playbook {Path(playbook).name}",
+            argv=build_ansible_argv(
+                playbook=playbook,
+                inventory=inventory,
+                user=user,
+                private_key_path=private_key_path,
+                extra_vars=extra_vars,
+            ),
+            executor=executor,
+            role=role,
+            options=current,
+        )

sonata_tasks/archive.py

@@ -0,0 +1,147 @@
+"""Ship a git commit's tree to a remote host as an extracted source archive."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import subprocess
+import tempfile
+from pathlib import Path
+
+from sonata_engine import Resource, TaskInputs
+from sonata_tasks.compensation import best_effort
+from sonata_tasks.transfer import RemoteProvider
+
+
+def _exec[RequestT](
+    provider: RemoteProvider[RequestT], request: RequestT, argv: tuple[str, ...]
+) -> str:
+    result = provider.exec_argv(request, argv=argv)
+    if not isinstance(result.return_code, int) or isinstance(result.return_code, bool):
+        raise RuntimeError("remote command returned no integer return_code")
+    if result.return_code != 0:
+        detail = result.stderr or result.stdout
+        raise RuntimeError(
+            f"remote command failed (exit {result.return_code})"
+            + (f": {detail}" if detail else "")
+        )
+    return result.stdout
+
+
+def _transfer_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    archive_path: Path,
+    remote_archive: str,
+) -> None:
+    result = provider.transfer_to(
+        request, source=archive_path, destination=remote_archive
+    )
+    if not isinstance(result.return_code, int) or isinstance(result.return_code, bool):
+        raise RuntimeError("transfer returned no integer return_code")
+    if result.return_code != 0:
+        detail = result.stderr or result.stdout
+        raise RuntimeError(
+            f"transfer failed (exit {result.return_code})"
+            + (f": {detail}" if detail else "")
+        )
+
+
+def _verify_remote_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    remote_archive: str,
+    local_checksum: str,
+) -> None:
+    try:
+        remote_checksum = _exec(
+            provider, request, ("sha256sum", remote_archive)
+        ).split()[0]
+        if remote_checksum != local_checksum:
+            raise RuntimeError(
+                f"sha256sum mismatch: local={local_checksum}, remote={remote_checksum}"
+            )
+    except BaseException as error:
+        best_effort(
+            error,
+            lambda: provider.exec_argv(request, argv=("rm", "-f", remote_archive)),
+            what="cleanup remote archive after failed verify",
+        )
+        raise
+
+
+def _extract_remote_archive[RequestT](
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+    remote_archive: str,
+    remote_source_dir: str,
+) -> None:
+    try:
+        _exec(provider, request, ("mkdir", "-p", remote_source_dir))
+        _exec(
+            provider, request, ("tar", "-xf", remote_archive, "-C", remote_source_dir)
+        )
+    except BaseException as error:
+        best_effort(
+            error,
+            lambda: provider.exec_argv(
+                request, argv=("rm", "-rf", remote_source_dir, remote_archive)
+            ),
+            what="cleanup after failed extract",
+        )
+        raise
+
+
+def source_archive_resource[RequestT](
+    *,
+    repo_root: Path,
+    commit: str,
+    remote_source_dir: str,
+    remote_archive: str,
+    provider: RemoteProvider[RequestT],
+    request: RequestT,
+) -> Resource[str]:
+    """Package ``commit`` locally and unpack it on the remote host.
+
+    The commit is exported with ``git archive``, transferred, verified against
+    its local SHA-256, and extracted into ``remote_source_dir``. Acquiring
+    returns ``remote_source_dir``; releasing best-effort deletes that extracted
+    directory on the remote host.
+    """
+
+    def acquire(_inputs: TaskInputs) -> str:
+        with tempfile.TemporaryDirectory() as tmp:
+            archive_path = Path(tmp) / "source.tar"
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(repo_root),
+                    "archive",
+                    "--format=tar",
+                    commit,
+                    "-o",
+                    str(archive_path),
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            checksum = hashlib.sha256(archive_path.read_bytes()).hexdigest()
+            _exec(provider, request, ("mkdir", "-p", str(Path(remote_archive).parent)))
+            _transfer_archive(provider, request, archive_path, remote_archive)
+            _verify_remote_archive(provider, request, remote_archive, checksum)
+            _extract_remote_archive(
+                provider, request, remote_archive, remote_source_dir
+            )
+        return remote_source_dir
+
+    def release(_inputs: TaskInputs, _state: str) -> None:
+        with contextlib.suppress(RuntimeError):
+            provider.exec_argv(request, argv=("rm", "-rf", remote_source_dir))
+
+    return Resource(
+        title=f"Acquire source archive at {remote_source_dir}",
+        acquire=acquire,
+        release=release,
+    )

sonata_tasks/buildx.py

@@ -0,0 +1,139 @@
+"""Manage a docker buildx builder as a resource."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import replace
+from typing import Any
+
+from sonata_engine import Resource, TaskInputs
+from sonata_tasks.command import CommandTask
+from sonata_tasks.compensation import best_effort
+from sonata_tasks.execution.models import CommandOptions, TaskResult
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+def _run(
+    inputs: TaskInputs,
+    executor: CommandTaskExecutor,
+    role: str,
+    options: CommandOptions,
+    *args: str,
+    expected: frozenset[int] = frozenset({0}),
+) -> TaskResult:
+    outcome = CommandTask(
+        title=f"docker buildx {' '.join(args)}",
+        argv=("docker", "buildx", *args),
+        executor=executor,
+        role=role,
+        options=replace(options, expected_exit_codes=expected),
+    ).run(inputs)
+    if outcome.value is None:
+        raise RuntimeError("docker buildx returned no command result")
+    return outcome.value
+
+
+def _create_argv(
+    name: str,
+    buildkitd_config: str | None,
+    driver_options: Sequence[str],
+) -> tuple[str, ...]:
+    argv = ["create", "--name", name, "--driver", "docker-container"]
+    if buildkitd_config is not None:
+        argv.extend(("--buildkitd-config", buildkitd_config))
+    for option in driver_options:
+        argv.extend(("--driver-opt", option))
+    argv.append("--use")
+    return tuple(argv)
+
+
+def _validate_output(validate: Callable[[str], None] | None, stdout: str) -> None:
+    if validate is not None:
+        validate(stdout)
+
+
+def buildx_builder_resource(
+    *,
+    name: str,
+    executor: CommandTaskExecutor,
+    role: str = "host",
+    options: CommandOptions | None = None,
+    requires: tuple[Resource[Any], ...] = (),
+    buildkitd_config: str | None = None,
+    # Driver options the created builder gets, as `--driver-opt` arguments. A
+    # `docker-container` builder runs buildkitd in a container of its own, so
+    # its `localhost` is itself: reaching a registry on the host's loopback
+    # needs `network=host` here, and buildkitd's own `[worker.oci] networkMode`
+    # does not substitute, because that governs the network of build steps
+    # rather than the daemon that pushes.
+    driver_options: Sequence[str] = (),
+    validate: Callable[[str], None] | None = None,
+    validation_key: str | None = None,
+    replace_existing: bool = False,
+) -> Resource[str]:
+    """Acquire a named docker buildx builder, bootstrapping it when missing.
+
+    Acquiring inspects the builder. A missing one — or one that
+    ``replace_existing`` asks to redo, which is removed first — is created as a
+    ``docker-container`` builder with ``--use`` and any ``driver_options``,
+    bootstrapped, and checked through ``validate``. Acquiring returns the builder
+    name for a builder this resource created, or ``"existing"`` when it left a
+    pre-existing builder untouched; releasing removes only the former.
+
+    Raises:
+        ValueError: If ``validate`` is configured without a ``validation_key``.
+
+    """
+    if validate is not None and not validation_key:
+        raise ValueError("validation_key is required when validate is configured")
+    current = options or CommandOptions()
+
+    def remove(inputs: TaskInputs) -> None:
+        _ = _run(inputs, executor, role, current, "rm", "--force", name)
+
+    def bootstrap(inputs: TaskInputs) -> None:
+        try:
+            _ = _run(
+                inputs,
+                executor,
+                role,
+                current,
+                *_create_argv(name, buildkitd_config, driver_options),
+            )
+            result = _run(
+                inputs, executor, role, current, "inspect", "--bootstrap", name
+            )
+            _validate_output(validate, result.stdout)
+        except BaseException as error:
+            best_effort(
+                error,
+                lambda: remove(inputs),
+                what=f"cleanup failed buildx builder {name}",
+            )
+            raise
+
+    def acquire(inputs: TaskInputs) -> str:
+        inspected = _run(
+            inputs, executor, role, current, "inspect", name, expected=frozenset({0, 1})
+        )
+        if inspected.return_code != 0:
+            bootstrap(inputs)
+            return name
+        if not replace_existing:
+            _validate_output(validate, inspected.stdout)
+            return "existing"
+        remove(inputs)
+        bootstrap(inputs)
+        return name
+
+    def release(inputs: TaskInputs, state: str) -> None:
+        if state != "existing":
+            remove(inputs)
+
+    return Resource(
+        title=f"Acquire {name} buildx builder",
+        acquire=acquire,
+        release=release,
+        requires=requires,
+        always_release=True,
+    )

sonata_tasks/command.py

@@ -0,0 +1,5 @@
+"""Compatibility import for the public command task."""
+
+from sonata_tasks.core.command import Argv, CommandTask
+
+__all__ = ["Argv", "CommandTask"]

sonata_tasks/compensation.py

@@ -0,0 +1,54 @@
+"""Helpers for undoing partial work without masking the original failure."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from sonata_engine import Resource, TaskInputs
+
+
+def best_effort(
+    error: BaseException, cleanup: Callable[[], object], *, what: str
+) -> None:
+    """Run cleanup without replacing the error that required it."""
+    try:
+        _ = cleanup()
+    except (OSError, RuntimeError) as cleanup_error:
+        error.add_note(
+            f"Best-effort {what} after a failed acquire failed: {cleanup_error}"
+        )
+
+
+def compensated_resource[T](
+    *,
+    title: str,
+    acquire: Callable[[TaskInputs], T],
+    compensate: Callable[[TaskInputs], object],
+    release: Callable[[TaskInputs, T], object] | None = None,
+    requires: tuple[Resource[Any], ...] = (),
+    always_release: bool = False,
+    revive: Callable[[Any], T] | None = None,
+) -> Resource[T]:
+    """Build a resource whose failed acquire performs best-effort compensation."""
+
+    def undo(inputs: TaskInputs, value: T) -> None:
+        _ = compensate(inputs) if release is None else release(inputs, value)
+
+    def acquire_with_compensation(inputs: TaskInputs) -> T:
+        try:
+            return acquire(inputs)
+        except BaseException as error:
+            best_effort(
+                error, lambda: compensate(inputs), what=f"compensation for {title}"
+            )
+            raise
+
+    return Resource(
+        title=title,
+        acquire=acquire_with_compensation,
+        release=undo,
+        requires=requires,
+        always_release=always_release,
+        revive=revive,
+    )

sonata_tasks/compose.py

@@ -0,0 +1,178 @@
+"""Deploy, wait for, and tear down a docker compose project."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from sonata_engine import Resource, Steps, TaskInputs
+from sonata_tasks.command import CommandTask
+from sonata_tasks.compensation import compensated_resource
+from sonata_tasks.execution.models import CommandOptions
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+@dataclass(frozen=True, slots=True)
+class DockerComposeProject:
+    """A compose project to run: its name, file, and readiness endpoint."""
+
+    name: str
+    file: Path
+    ready_url: str
+    build: bool = True
+
+
+class DeployDockerCompose(CommandTask):
+    """Bring a compose project up detached and wait for its services."""
+
+    def __init__(
+        self,
+        project: DockerComposeProject,
+        *,
+        executor: CommandTaskExecutor,
+        role: str = "host",
+        options: CommandOptions | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Configure the ``docker compose up -d --wait`` command.
+
+        ``--build`` is added unless ``project.build`` is false. ``title``
+        defaults to one naming the project.
+        """
+        super().__init__(
+            title=title or f"Deploy Docker Compose project {project.name}",
+            argv=(
+                "docker",
+                "compose",
+                "-f",
+                str(project.file),
+                "-p",
+                project.name,
+                "up",
+                "-d",
+                *(("--build",) if project.build else ()),
+                "--wait",
+            ),
+            executor=executor,
+            role=role,
+            options=options,
+        )
+
+
+class WaitForDockerCompose(CommandTask):
+    """Poll the project's readiness URL until it answers."""
+
+    def __init__(
+        self,
+        project: DockerComposeProject,
+        *,
+        executor: CommandTaskExecutor,
+        role: str = "host",
+        options: CommandOptions | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Configure the ``curl`` retry loop against ``project.ready_url``.
+
+        ``title`` defaults to one naming the project.
+        """
+        super().__init__(
+            title=title or f"Wait for Docker Compose project {project.name}",
+            argv=(
+                "curl",
+                "-fsS",
+                "--retry",
+                "60",
+                "--retry-delay",
+                "1",
+                "--retry-connrefused",
+                "--retry-all-errors",
+                project.ready_url,
+            ),
+            executor=executor,
+            role=role,
+            options=options,
+        )
+
+
+class DestroyDockerCompose(CommandTask):
+    """Bring a compose project down, optionally dropping volumes and orphans."""
+
+    def __init__(
+        self,
+        project: DockerComposeProject,
+        *,
+        executor: CommandTaskExecutor,
+        role: str = "host",
+        options: CommandOptions | None = None,
+        title: str | None = None,
+        remove_volumes: bool = False,
+        remove_orphans: bool = False,
+    ) -> None:
+        """Configure the ``docker compose down`` command.
+
+        ``remove_volumes`` and ``remove_orphans`` add ``--volumes`` and
+        ``--remove-orphans`` respectively; ``title`` defaults to one naming the
+        project.
+        """
+        argv = [
+            "docker",
+            "compose",
+            "-f",
+            str(project.file),
+            "-p",
+            project.name,
+            "down",
+        ]
+        if remove_volumes:
+            argv.append("--volumes")
+        if remove_orphans:
+            argv.append("--remove-orphans")
+        super().__init__(
+            title=title or f"Destroy Docker Compose project {project.name}",
+            argv=tuple(argv),
+            executor=executor,
+            role=role,
+            options=options,
+        )
+
+
+def docker_compose_resource(
+    project: DockerComposeProject,
+    *,
+    executor: CommandTaskExecutor,
+    role: str = "host",
+    options: CommandOptions | None = None,
+    remove_volumes: bool = False,
+    remove_orphans: bool = False,
+    requires: tuple[Resource[Any], ...] = (),
+) -> Resource[DockerComposeProject]:
+    """Manage the supplied project; acquisition performs deploy then readiness."""
+    deploy = Steps(
+        title=f"Acquire Docker Compose project {project.name}",
+        steps=(
+            DeployDockerCompose(project, executor=executor, role=role, options=options),
+            WaitForDockerCompose(
+                project, executor=executor, role=role, options=options
+            ),
+        ),
+    )
+    destroy = DestroyDockerCompose(
+        project,
+        executor=executor,
+        role=role,
+        options=options,
+        remove_volumes=remove_volumes,
+        remove_orphans=remove_orphans,
+    )
+
+    def acquire(inputs: TaskInputs) -> DockerComposeProject:
+        _ = deploy.run(inputs)
+        return project
+
+    return compensated_resource(
+        title=f"Acquire Docker Compose project {project.name}",
+        acquire=acquire,
+        compensate=destroy.run,
+        requires=requires,
+    )

sonata_tasks/composites.py

@@ -0,0 +1,59 @@
+"""Turn already-resolved command specs into a runnable step sequence."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from sonata_engine import Steps
+from sonata_tasks.command import CommandTask
+from sonata_tasks.core.fingerprint import fingerprint_digest
+from sonata_tasks.execution.models import CommandTaskSpec
+from sonata_tasks.execution.ports import CommandTaskExecutor
+
+
+def command_specs_composite(
+    commands: Sequence[CommandTaskSpec], executor: CommandTaskExecutor, *, title: str
+) -> Steps:
+    """Wrap each spec in a :class:`CommandTask` and collect them as ``Steps``.
+
+    ``title`` labels the composite; a spec without a summary is titled by its
+    position in ``commands``.
+    """
+    return Steps(
+        title=title,
+        steps=tuple(
+            CommandTask(
+                title=spec.summary or f"Command {index}",
+                argv=spec.argv,
+                executor=executor,
+                role=spec.role,
+                options=spec.options,
+            )
+            for index, spec in enumerate(commands)
+        ),
+    )
+
+
+def command_specs_fingerprint(
+    commands: Sequence[CommandTaskSpec], executor: CommandTaskExecutor
+) -> str:
+    """Hash the same static command inputs used by CommandTask fingerprints."""
+    return fingerprint_digest(
+        {
+            "commands": tuple(
+                {
+                    "argv": spec.argv,
+                    "role": spec.role,
+                    "binding_key": executor.binding_key(spec.role),
+                    "options": {
+                        "cwd": spec.options.cwd,
+                        "env": spec.options.env,
+                        "remote_dir": spec.options.remote_dir,
+                        "expected_exit_codes": spec.options.expected_exit_codes,
+                        "timeout_seconds": spec.options.timeout_seconds,
+                    },
+                }
+                for spec in commands
+            )
+        }
+    )

sonata_tasks/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core task mechanisms."""
+
+from sonata_tasks.core.command import CommandTask
+
+__all__ = ["CommandTask"]