verulla-cli 0.0.2__py3-none-any.whl

verulla_cli/emulate.py

@@ -0,0 +1,124 @@
+"""Docker-based local emulation for `verulla dev` (M4 T4.3).
+
+This mirrors the manifest -> BuildPlan translation layer shared with
+`deploy`, but builds and runs the resulting image locally via the
+`docker` Python SDK instead of shipping it to the control plane.
+
+Design note on testability (same honesty pattern as the no-Postgres-locally
+constraint elsewhere in this codebase): there is no Docker daemon in this
+sandbox. `generate_dockerfile` is pure logic and is fully tested for real.
+`DockerRunner`'s orchestration (which SDK calls happen, in what order, with
+what arguments, how errors map to clean messages) is unit-tested against a
+hand-rolled fake Docker client double. A real, skip-guarded integration test
+exercises the actual `docker` SDK end to end on a machine that has Docker.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from verulla_manifest.dockerfile import generate_dockerfile
+from verulla_manifest.translate import FunctionBuild
+
+
+class EmulationError(Exception):
+    """Raised for any failure building or running a local preview container."""
+
+
+class DockerRunner:
+    """Thin wrapper over the docker SDK; accepts an injected client for testing."""
+
+    def __init__(self, client=None):
+        if client is not None:
+            self.client = client
+            return
+        try:
+            import docker
+
+            self.client = docker.from_env()
+            self.client.ping()
+        except Exception as exc:  # noqa: BLE001 - docker SDK raises many exception types here
+            raise EmulationError(
+                f"could not connect to Docker (is it installed and running?): {exc}"
+            ) from exc
+
+    def stop_and_remove(self, name: str) -> None:
+        import docker.errors
+
+        try:
+            container = self.client.containers.get(name)
+        except docker.errors.NotFound:
+            return
+        try:
+            container.stop(timeout=2)
+        except docker.errors.APIError:
+            pass
+        container.remove(force=True)
+
+    def build_image(self, context_dir: Path, dockerfile_name: str, tag: str) -> str:
+        import docker.errors
+
+        try:
+            image, _logs = self.client.images.build(
+                path=str(context_dir), dockerfile=dockerfile_name, tag=tag, rm=True
+            )
+        except docker.errors.BuildError as exc:
+            raise EmulationError(f"docker build failed for {tag!r}: {exc}") from exc
+        except docker.errors.APIError as exc:
+            raise EmulationError(f"docker API error building {tag!r}: {exc}") from exc
+        return image.id
+
+    def check_image(self, context_dir: Path, dockerfile_name: str, tag: str) -> str:
+        """Build a smoke-test Dockerfile and return its ROUTE status log lines."""
+        import docker.errors
+
+        try:
+            _image, logs = self.client.images.build(
+                path=str(context_dir), dockerfile=dockerfile_name, tag=tag, rm=True
+            )
+        except docker.errors.BuildError as exc:
+            logs = getattr(exc, "build_log", [])
+            output = "".join(
+                item.get("stream", "") if isinstance(item, dict) else str(item)
+                for item in logs
+            )
+            if "ROUTE " in output:
+                return output
+            detail = output.strip() or str(exc)
+            raise EmulationError(f"docker check build failed: {detail}") from exc
+        except docker.errors.APIError as exc:
+            raise EmulationError(f"docker API error checking routes: {exc}") from exc
+        return "".join(
+            str(item.get("stream", "")) if isinstance(item, dict) else str(item)
+            for item in logs
+        )
+
+    def run_container(self, tag: str, host_port: int, container_port: int, name: str) -> str:
+        import docker.errors
+
+        self.stop_and_remove(name)
+        try:
+            container = self.client.containers.run(
+                tag,
+                detach=True,
+                ports={f"{container_port}/tcp": host_port},
+                name=name,
+            )
+        except docker.errors.APIError as exc:
+            raise EmulationError(f"docker run failed for {name!r}: {exc}") from exc
+        return container.id
+
+
+def emulate_function(build: FunctionBuild, runner: DockerRunner, host_port: int) -> str:
+    """Build and run one function's container locally; returns its preview URL."""
+    plan = build.build_plan
+    if plan.dockerfile_path is not None:
+        dockerfile_name = plan.dockerfile_path
+    else:
+        dockerfile_name = ".verulla.Dockerfile"
+        (build.src_root / dockerfile_name).write_text(generate_dockerfile(plan))
+    tag = f"verulla-dev-{build.name}:latest"
+    container_name = f"verulla-dev-{build.name}"
+    runner.build_image(build.src_root, dockerfile_name, tag)
+    runner.run_container(tag, host_port, plan.port, container_name)
+    return f"http://localhost:{host_port}"