samstack 0.1.0__py3-none-any.whl

samstack/__init__.py

@@ -0,0 +1,18 @@
+from samstack._errors import (
+    DockerNetworkError,
+    LocalStackStartupError,
+    SamBuildError,
+    SamStackError,
+    SamStartupError,
+)
+from samstack.settings import SamStackSettings, load_settings
+
+__all__ = [
+    "DockerNetworkError",
+    "LocalStackStartupError",
+    "SamBuildError",
+    "SamStackError",
+    "SamStartupError",
+    "SamStackSettings",
+    "load_settings",
+]

samstack/_constants.py

@@ -0,0 +1,6 @@
+"""Internal constants shared across samstack fixtures."""
+
+# LocalStack accepts any non-empty value for AWS credentials.
+# "test" is its documented default and is not configurable.
+LOCALSTACK_ACCESS_KEY = "test"
+LOCALSTACK_SECRET_KEY = "test"

samstack/_errors.py

@@ -0,0 +1,38 @@
+class SamStackError(Exception):
+    """Base exception for all samstack errors."""
+
+
+class SamBuildError(SamStackError):
+    """sam build container exited with non-zero status."""
+
+    def __init__(self, logs: str) -> None:
+        self.logs = logs
+        super().__init__(f"sam build failed.\n\nLogs:\n{logs}")
+
+
+class SamStartupError(SamStackError):
+    """SAM process did not bind port within timeout."""
+
+    def __init__(self, port: int, log_tail: str) -> None:
+        self.port = port
+        self.log_tail = log_tail
+        super().__init__(
+            f"SAM did not start on port {port} within timeout.\n\nLog tail:\n{log_tail}"
+        )
+
+
+class LocalStackStartupError(SamStackError):
+    """LocalStack container did not become healthy."""
+
+    def __init__(self, log_tail: str) -> None:
+        self.log_tail = log_tail
+        super().__init__(f"LocalStack did not become healthy.\n\nLog tail:\n{log_tail}")
+
+
+class DockerNetworkError(SamStackError):
+    """Failed to create or attach shared Docker network."""
+
+    def __init__(self, name: str, reason: str) -> None:
+        self.name = name
+        self.reason = reason
+        super().__init__(f"Docker network '{name}' error: {reason}")

samstack/_process.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from samstack._errors import SamStartupError
+
+if TYPE_CHECKING:
+    from docker.models.containers import Container
+
+
+def tail_log_file(path: Path, lines: int = 50) -> str:
+    """Return the last *lines* lines of a log file, or '' if missing."""
+    if not path.exists():
+        return ""
+    content = path.read_text(errors="replace")
+    return "\n".join(content.splitlines()[-lines:])
+
+
+def wait_for_port(
+    host: str,
+    port: int,
+    log_path: Path,
+    timeout: float = 120.0,
+    interval: float = 0.5,
+) -> None:
+    """Block until *port* accepts TCP connections or raise SamStartupError."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            socket.create_connection((host, port), timeout=1.0).close()
+            return
+        except OSError:
+            time.sleep(interval)
+    raise SamStartupError(port=port, log_tail=tail_log_file(log_path))
+
+
+def wait_for_http(
+    host: str,
+    port: int,
+    log_path: Path,
+    path: str = "/",
+    timeout: float = 120.0,
+    interval: float = 1.0,
+) -> None:
+    """Block until an HTTP GET returns any response (any status code).
+
+    Unlike wait_for_port (TCP probe), this confirms the HTTP server is
+    fully initialised and handling requests — not just that the port forwarder
+    is listening.  Raises SamStartupError on timeout.
+    """
+    url = f"http://{host}:{port}{path}"
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            urllib.request.urlopen(url, timeout=2.0)  # noqa: S310
+            return
+        except urllib.error.HTTPError:
+            # Any HTTP error (4xx/5xx) means the server is up
+            return
+        except (urllib.error.URLError, OSError):
+            time.sleep(interval)
+    raise SamStartupError(port=port, log_tail=tail_log_file(log_path))
+
+
+def stream_logs_to_file(container: Container, log_path: Path) -> threading.Thread:
+    """Stream Docker container stdout/stderr to *log_path* in a daemon thread.
+
+    *container* is a Docker SDK container object (docker.models.containers.Container).
+    """
+
+    def _stream() -> None:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with log_path.open("a") as f:
+                for chunk in container.logs(stream=True, follow=True):
+                    f.write(chunk.decode(errors="replace"))
+                    f.flush()
+        except Exception as exc:
+            try:
+                with log_path.open("a") as f:
+                    f.write(f"\n[samstack] log streaming failed: {exc}\n")
+            except Exception:
+                pass
+
+    t = threading.Thread(target=_stream, daemon=True)
+    t.start()
+    return t
+
+
+def run_one_shot_container(
+    image: str,
+    command: str | list[str],
+    volumes: dict[str, dict[str, str]],
+    working_dir: str = "/var/task",
+    network: str | None = None,
+    environment: dict[str, str] | None = None,
+) -> tuple[str, int]:
+    """Run a container to completion. Returns (logs, exit_code)."""
+    import docker as docker_sdk
+
+    client = docker_sdk.from_env()
+    kwargs: dict[str, Any] = {"network": network} if network else {}
+    if environment:
+        kwargs["environment"] = environment
+    container = client.containers.run(
+        image=image,
+        command=command,
+        volumes=volumes,
+        working_dir=working_dir,
+        detach=True,
+        **kwargs,
+    )
+    try:
+        result = container.wait()
+        logs = container.logs().decode(errors="replace")
+        return logs, result["StatusCode"]
+    finally:
+        container.remove(force=True)

samstack/fixtures/_sam_container.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import os
+import platform
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Literal
+
+from testcontainers.core.container import DockerContainer
+
+from samstack._process import stream_logs_to_file, wait_for_http, wait_for_port
+from samstack.settings import SamStackSettings
+
+DOCKER_SOCKET = "/var/run/docker.sock"
+
+
+def _is_ci() -> bool:
+    """Return True when running inside a CI environment (GitHub Actions, GitLab CI, etc.)."""
+    return bool(os.environ.get("CI"))
+
+
+def _extra_hosts() -> dict[str, str]:
+    """On Linux (no Docker Desktop), map host.docker.internal to the host gateway."""
+    if platform.system() == "Darwin":
+        return {}
+    return {"host.docker.internal": "host-gateway"}
+
+
+def build_sam_args(
+    port: int,
+    env_vars_host_path: str,
+    docker_network: str,
+    warm_containers: str,
+    settings_extra_args: list[str],
+    fixture_extra_args: list[str],
+) -> list[str]:
+    """Return the CLI arg list shared by start-api and start-lambda."""
+    skip_pull: list[str] = [] if _is_ci() else ["--skip-pull-image"]
+    return [
+        *skip_pull,
+        "--warm-containers",
+        warm_containers,
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(port),
+        "--env-vars",
+        env_vars_host_path,
+        "--docker-network",
+        docker_network,
+        "--container-host",
+        "host.docker.internal",
+        "--container-host-interface",
+        "0.0.0.0",
+        *settings_extra_args,
+        *fixture_extra_args,
+    ]
+
+
+@contextmanager
+def _run_sam_service(
+    settings: SamStackSettings,
+    docker_network: str,
+    subcommand: Literal["start-api", "start-lambda"],
+    port: int,
+    warm_containers: str,
+    settings_extra_args: list[str],
+    fixture_extra_args: list[str],
+    log_filename: str,
+    wait_mode: Literal["http", "port"],
+) -> Iterator[str]:
+    """Start a `sam local <subcommand>` container and yield its endpoint URL."""
+    log_dir = settings.project_root / settings.log_dir
+    log_path = log_dir / log_filename
+    host_path = str(settings.project_root)
+    env_vars_host_path = str(log_dir / "env_vars.json")
+
+    args = build_sam_args(
+        port=port,
+        env_vars_host_path=env_vars_host_path,
+        docker_network=docker_network,
+        warm_containers=warm_containers,
+        settings_extra_args=settings_extra_args,
+        fixture_extra_args=fixture_extra_args,
+    )
+    command = ["sam", "local", subcommand, "--template", settings.template, *args]
+
+    container = create_sam_container(
+        settings=settings,
+        docker_network=docker_network,
+        host_path=host_path,
+        port=port,
+        command=command,
+    )
+    container.start()
+    inner = container.get_wrapped_container()
+    assert inner is not None, "SAM container failed to start"
+    stream_logs_to_file(inner, log_path)
+
+    host_port = int(container.get_exposed_port(port))
+    if wait_mode == "http":
+        wait_for_http("127.0.0.1", host_port, log_path=log_path, timeout=120.0)
+    else:
+        wait_for_port("127.0.0.1", host_port, log_path=log_path, timeout=120.0)
+
+    try:
+        yield f"http://127.0.0.1:{host_port}"
+    finally:
+        container.stop()
+
+
+def create_sam_container(
+    settings: SamStackSettings,
+    docker_network: str,
+    host_path: str,
+    port: int,
+    command: list[str],
+) -> DockerContainer:
+    """Build a DockerContainer for `sam local start-*` with all standard mounts and env."""
+    return (
+        DockerContainer(settings.sam_image)
+        .with_kwargs(
+            network=docker_network,
+            extra_hosts=_extra_hosts(),
+            working_dir=host_path,
+        )
+        .with_volume_mapping(host_path, host_path, "rw")
+        .with_volume_mapping(DOCKER_SOCKET, DOCKER_SOCKET, "rw")
+        .with_exposed_ports(port)
+        .with_env("SAM_CLI_CONTAINER_CONNECTION_TIMEOUT", "60")
+        .with_env("DOCKER_DEFAULT_PLATFORM", settings.docker_platform)
+        .with_command(command)
+    )

samstack/fixtures/localstack.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterator
+from uuid import uuid4
+
+import docker as docker_sdk
+import pytest
+from testcontainers.localstack import LocalStackContainer
+
+from samstack._errors import DockerNetworkError
+from samstack.fixtures._sam_container import DOCKER_SOCKET
+from samstack.settings import SamStackSettings
+
+
+@pytest.fixture(scope="session")
+def docker_network_name() -> str:
+    """Return the name for the shared Docker bridge network.
+
+    Override this fixture to use a fixed or externally-managed network name.
+    """
+    return f"samstack-{uuid4().hex[:8]}"
+
+
+@pytest.fixture(scope="session")
+def docker_network(docker_network_name: str) -> Iterator[str]:
+    """Create a Docker bridge network shared by LocalStack and SAM containers."""
+    name = docker_network_name
+    client = docker_sdk.from_env()
+    try:
+        network = client.networks.create(name, driver="bridge")
+    except Exception as exc:
+        raise DockerNetworkError(name=name, reason=str(exc)) from exc
+    try:
+        yield name
+    finally:
+        try:
+            network.reload()
+            for container in network.containers:
+                try:
+                    container.stop(timeout=5)
+                    container.remove(force=True)
+                except Exception:
+                    network.disconnect(container, force=True)
+            network.remove()
+        except Exception as exc:
+            warnings.warn(
+                f"samstack: failed to clean up Docker network '{name}': {exc}",
+                stacklevel=1,
+            )
+
+
+@pytest.fixture(scope="session")
+def localstack_container(
+    samstack_settings: SamStackSettings,
+    docker_network: str,
+) -> Iterator[LocalStackContainer]:
+    """Start LocalStack and connect it to the shared Docker network."""
+    container = LocalStackContainer(image=samstack_settings.localstack_image)
+    container.with_volume_mapping(DOCKER_SOCKET, DOCKER_SOCKET, "rw")
+    container.start()
+
+    client = docker_sdk.from_env()
+    try:
+        network = client.networks.get(docker_network)
+        inner = container.get_wrapped_container()
+        assert inner is not None, "LocalStack container failed to start"
+        network.connect(inner.id, aliases=["localstack"])
+    except Exception as exc:
+        container.stop()
+        raise DockerNetworkError(name=docker_network, reason=str(exc)) from exc
+
+    try:
+        yield container
+    finally:
+        try:
+            network = client.networks.get(docker_network)
+            inner = container.get_wrapped_container()
+            if inner is not None:
+                network.disconnect(inner.id, force=True)
+        except Exception as exc:
+            warnings.warn(
+                f"samstack: failed to disconnect LocalStack from network '{docker_network}': {exc}",
+                stacklevel=1,
+            )
+        container.stop()
+
+
+@pytest.fixture(scope="session")
+def localstack_endpoint(localstack_container: LocalStackContainer) -> str:
+    """Return the host-accessible LocalStack URL for use in boto3 clients."""
+    return localstack_container.get_url()