moved container utils

Author: Andrei Neagu

packages/service-library/src/servicelib/container_utils.py

@@ -0,0 +1,102 @@
+import asyncio
+import logging
+from collections.abc import Sequence
+from typing import Any, Final
+
+from aiodocker import Docker, DockerError
+from aiodocker.execs import Exec
+from aiodocker.stream import Stream
+from common_library.errors_classes import OsparcErrorMixin
+from pydantic import NonNegativeFloat
+
+
+class BaseContainerUtilsError(OsparcErrorMixin, Exception):
+    pass
+
+
+class ContainerExecContainerNotFoundError(BaseContainerUtilsError):
+    msg_template = "Container '{container_name}' was not found"
+
+
+class ContainerExecTimeoutError(BaseContainerUtilsError):
+    msg_template = "Timed out after {timeout} while executing: '{command}'"
+
+
+class ContainerExecCommandFailedError(BaseContainerUtilsError):
+    msg_template = (
+        "Command '{command}' exited with code '{exit_code}'"
+        "and output: '{command_result}'"
+    )
+
+
+_HTTP_404_NOT_FOUND: Final[int] = 404
+
+_logger = logging.getLogger(__name__)
+
+
+async def _execute_command(container_name: str, command: str | Sequence[str]) -> str:
+    async with Docker() as docker:
+        container = await docker.containers.get(container_name)
+
+        # Start the command inside the container
+        exec_instance: Exec = await container.exec(
+            cmd=command, stdout=True, stderr=True, tty=False
+        )
+
+        # Start the execution
+        stream: Stream = exec_instance.start(detach=False)
+
+        command_result: str = ""
+        async with stream:
+            while stream_message := await stream.read_out():
+                command_result += stream_message.data.decode()
+
+        inspect_result: dict[str, Any] = await exec_instance.inspect()
+        exit_code: int | None = inspect_result.get("ExitCode", None)
+        if exit_code != 0:
+            raise ContainerExecCommandFailedError(
+                command=command, exit_code=exit_code, command_result=command_result
+            )
+
+    _logger.debug("Command result:\n$ '%s'\n%s", command, command_result)
+    return command_result
+
+
+async def run_command_in_container(
+    container_name: str,
+    *,
+    command: str | Sequence[str],
+    timeout: NonNegativeFloat = 1.0,
+):
+    """
+    Runs `command` in target container and returns the command's output if
+    command's exit code is 0.
+
+    Arguments:
+        container_name -- name of the container in which to run the command
+        command -- string or sequence of strings to run as command
+
+    Keyword Arguments:
+        timeout -- max time for the command to return a result in (default: {1.0})
+
+    Raises:
+        ContainerExecTimeoutError: command execution did not finish in time
+        ContainerExecContainerNotFoundError: target container is not present
+        ContainerExecCommandFailedError: command finished with not 0 exit code
+        DockerError: propagates error from docker engine
+
+    Returns:
+        stdout + stderr produced by the command is returned
+    """
+    try:
+        return await asyncio.wait_for(
+            _execute_command(container_name, command), timeout
+        )
+    except DockerError as e:
+        if e.status == _HTTP_404_NOT_FOUND:
+            raise ContainerExecContainerNotFoundError(
+                container_name=container_name
+            ) from e
+        raise
+    except TimeoutError as e:
+        raise ContainerExecTimeoutError(timeout=timeout, command=command) from e

packages/service-library/tests/test_container_utils.py

@@ -0,0 +1,55 @@
+# pylint: disable=redefined-outer-name
+
+import contextlib
+from collections.abc import AsyncIterable
+
+import aiodocker
+import pytest
+from servicelib.container_utils import (
+    ContainerExecCommandFailedError,
+    ContainerExecContainerNotFoundError,
+    ContainerExecTimeoutError,
+    run_command_in_container,
+)
+
+
+@pytest.fixture
+async def running_container_name() -> AsyncIterable[str]:
+    async with aiodocker.Docker() as client:
+        container = await client.containers.run(
+            config={
+                "Image": "alpine:latest",
+                "Cmd": ["/bin/ash", "-c", "sleep 10000"],
+            }
+        )
+        container_inspect = await container.show()
+
+        yield container_inspect["Name"][1:]
+
+        with contextlib.suppress(aiodocker.DockerError):
+            await container.kill()
+        await container.delete()
+
+
+async def test_run_command_in_container_container_not_found():
+    with pytest.raises(ContainerExecContainerNotFoundError):
+        await run_command_in_container("missing_container", command="")
+
+
+async def test_run_command_in_container_command_timed_out(running_container_name: str):
+    with pytest.raises(ContainerExecTimeoutError):
+        await run_command_in_container(
+            running_container_name, command="sleep 10", timeout=0.1
+        )
+
+
+async def test_run_command_in_container_none_zero_exit_code(
+    running_container_name: str,
+):
+    with pytest.raises(ContainerExecCommandFailedError):
+        await run_command_in_container(running_container_name, command="exit 1")
+
+
+async def test_run_command_in_container(running_container_name: str):
+    result = await run_command_in_container(running_container_name, command="ls -lah")
+    assert len(result) > 0