FastAPI-fastkit 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

fastapi_fastkit/__init__.py

@@ -1 +1 @@
-__version__ = 'v1.4.0'
+__version__ = 'v1.5.0'

fastapi_fastkit/backend/inspection/context.py

@@ -43,6 +43,10 @@ class InspectionContext:
     warnings: List[str] = field(default_factory=list)
     #: Populated by a test strategy so later checks can reuse the environment.
     venv_path: Optional[str] = None
+    #: Populated when a test strategy already exercised the app's HTTP surface
+    #: (the Docker strategy probes the running container), so the Smoke Test
+    #: step reuses that verdict instead of booting a second server.
+    smoke_result: Optional[bool] = None
 
     def add_error(self, message: str) -> None:
         """Record a fatal finding."""

fastapi_fastkit/backend/inspection/core.py

@@ -252,8 +252,12 @@ class TemplateInspector:
             ("Configuration Consistency", self._check_configuration_consistency),
             ("FastAPI Implementation", self._check_fastapi_implementation),
             ("Placeholder Substitution", self._check_no_placeholder_residue),
-            ("Template Tests", self._test_template),
+            # Compile Check is a pure static check: it runs before the (much
+            # heavier) Template Tests so a syntax error is reported without
+            # waiting for an environment, and so it never observes files a
+            # containerised test run left behind.
             ("Compile Check", self._check_compileall),
+            ("Template Tests", self._test_template),
             ("Type Check", self._check_mypy),
             ("Smoke Test", self._check_smoke_test),
             ("Dependency Freshness", self._check_dependency_freshness),

fastapi_fastkit/backend/inspection/docker.py

@@ -7,6 +7,7 @@
 # @author bnbong
 # --------------------------------------------------------------------------
 import json
+import os
 import subprocess
 import time
 from typing import Any, Dict, List, Optional, Sequence
@@ -14,6 +15,12 @@ from typing import Any, Dict, List, Optional, Sequence
 from fastapi_fastkit.utils.logging import debug_log
 
 COMPOSE_COMMAND = "docker-compose"
+#: Fallback for hosts that only ship the ``docker compose`` CLI plugin.
+COMPOSE_PLUGIN_COMMAND = ["docker", "compose"]
+#: Resolved compose invocation, switched by :meth:`DockerCompose.is_available`.
+_compose_prefix: List[str] = [COMPOSE_COMMAND]
+#: Throwaway image used to give bind-mounted files back to the host user.
+RECLAIM_IMAGE = "alpine:3.20"
 SHORT_TIMEOUT = 10
 STATUS_TIMEOUT = 30
 CLEANUP_TIMEOUT = 60
@@ -43,27 +50,49 @@ class DockerCompose:
             debug_log(f"Command {' '.join(args)} failed: {e}", "warning")
             return None
 
+    @staticmethod
+    def compose_command() -> List[str]:
+        """Return the compose invocation resolved by :meth:`is_available`."""
+        return list(_compose_prefix)
+
     def _compose(
         self, args: Sequence[str], timeout: int
     ) -> Optional[subprocess.CompletedProcess[str]]:
         """Run a docker-compose subcommand against the configured compose file."""
         return self._run(
-            [COMPOSE_COMMAND, "-f", self.compose_file, *args], timeout=timeout
+            [*self.compose_command(), "-f", self.compose_file, *args], timeout=timeout
         )
 
+    @staticmethod
+    def _probe(command: Sequence[str]) -> bool:
+        """Return whether ``command`` exits successfully."""
+        try:
+            result = subprocess.run(
+                list(command), capture_output=True, text=True, timeout=SHORT_TIMEOUT
+            )
+        except (subprocess.TimeoutExpired, OSError):
+            return False
+        return result.returncode == 0
+
     @staticmethod
     def is_available() -> bool:
-        """Check that both docker and docker-compose respond."""
-        for command in (["docker", "--version"], [COMPOSE_COMMAND, "--version"]):
-            try:
-                result = subprocess.run(
-                    command, capture_output=True, text=True, timeout=SHORT_TIMEOUT
-                )
-            except (subprocess.TimeoutExpired, OSError):
-                return False
-            if result.returncode != 0:
-                return False
-        return True
+        """Check that docker responds and a compose implementation exists.
+
+        ``docker-compose`` stays the preferred command; hosts that only ship
+        the ``docker compose`` CLI plugin fall back to it.
+        """
+        global _compose_prefix
+
+        if not DockerCompose._probe(["docker", "--version"]):
+            return False
+        if DockerCompose._probe([COMPOSE_COMMAND, "--version"]):
+            _compose_prefix = [COMPOSE_COMMAND]
+            return True
+        if DockerCompose._probe([*COMPOSE_PLUGIN_COMMAND, "version"]):
+            debug_log("Falling back to the 'docker compose' CLI plugin", "info")
+            _compose_prefix = list(COMPOSE_PLUGIN_COMMAND)
+            return True
+        return False
 
     def _services(self, timeout: int) -> List[Dict[str, Any]]:
         """Return the parsed ``docker-compose ps --format json`` entries."""
@@ -71,8 +100,34 @@ class DockerCompose:
         if result is None or result.returncode != 0:
             return []
 
+        # Compose sometimes interleaves ``time="..." level=warning`` log lines
+        # with the JSON payload, so only JSON-looking lines are considered.
+        payload = "\n".join(
+            line
+            for line in result.stdout.splitlines()
+            if line.strip().startswith(("[", "{"))
+        ).strip()
+        if not payload:
+            return []
+
+        # Compose < v2.21 prints a single JSON array, newer versions print one
+        # JSON object per line (NDJSON).
+        try:
+            document = json.loads(payload)
+        except json.JSONDecodeError:
+            return DockerCompose._parse_json_lines(payload)
+
+        if isinstance(document, dict):
+            return [document]
+        if isinstance(document, list):
+            return [entry for entry in document if isinstance(entry, dict)]
+        return []
+
+    @staticmethod
+    def _parse_json_lines(payload: str) -> List[Dict[str, Any]]:
+        """Parse NDJSON output, skipping malformed or non-object lines."""
         services: List[Dict[str, Any]] = []
-        for line in result.stdout.strip().split("\n"):
+        for line in payload.split("\n"):
             if not line.strip():
                 continue
             try:
@@ -109,7 +164,7 @@ class DockerCompose:
         """Build and start the compose services in the background."""
         result = self._compose(["up", "-d", "--build"], timeout=timeout)
         if result is None:
-            raise subprocess.TimeoutExpired(COMPOSE_COMMAND, timeout)
+            raise subprocess.TimeoutExpired(" ".join(self.compose_command()), timeout)
         return result
 
     def wait_until_healthy(self, timeout: int) -> None:
@@ -166,6 +221,50 @@ class DockerCompose:
         debug_log("All required services are running", "info")
         return None
 
+    def published_port(self, service_hint: str = "app") -> Optional[int]:
+        """Return the host port the app container publishes, if any.
+
+        ``docker-compose ps --format json`` reports a ``Publishers`` list per
+        service; an entry with a non-zero ``PublishedPort`` is a port bound on
+        the host, which is what a smoke test can reach. Services whose name
+        contains ``service_hint`` are preferred, so a database that happens to
+        publish a port is never mistaken for the application.
+        """
+        services = self._services(timeout=STATUS_TIMEOUT)
+        if not services:
+            return None
+
+        def _matches(service: Dict[str, Any]) -> bool:
+            name = f"{service.get('Service', '')} {service.get('Name', '')}"
+            return service_hint in name
+
+        for candidate in (
+            [entry for entry in services if _matches(entry)],
+            services,
+        ):
+            for service in candidate:
+                port = self._first_published_port(service)
+                if port is not None:
+                    return port
+        return None
+
+    @staticmethod
+    def _first_published_port(service: Dict[str, Any]) -> Optional[int]:
+        """Extract the first host-bound port from one ``ps`` entry."""
+        publishers = service.get("Publishers")
+        if not isinstance(publishers, list):
+            return None
+        for publisher in publishers:
+            if not isinstance(publisher, dict):
+                continue
+            try:
+                port = int(publisher.get("PublishedPort", 0))
+            except (TypeError, ValueError):
+                continue
+            if port > 0:
+                return port
+        return None
+
     def exec_tests(
         self, use_test_script: bool
     ) -> Optional[subprocess.CompletedProcess[str]]:
@@ -176,10 +275,46 @@ class DockerCompose:
             command = ["exec", "-T", "app", "python", "-m", "pytest", "tests/", "-v"]
         return self._compose(command, timeout=TEST_TIMEOUT)
 
+    def reclaim_bind_mount_ownership(self) -> None:
+        """Give the bind-mounted project directory back to the host user.
+
+        Containers run as root, so a test run inside the stack leaves
+        root-owned artefacts (``__pycache__``, ``.pytest_cache``, ...) in the
+        mounted project. Later host-side steps and the temp directory cleanup
+        cannot touch those and fail with a PermissionError, so the ownership
+        is reset from inside a throwaway container. Best effort: a failure
+        here is never worth failing an inspection over.
+        """
+        if not hasattr(os, "getuid"):  # pragma: no cover - Windows hosts
+            return
+
+        uid, gid = os.getuid(), os.getgid()
+        if uid == 0:
+            return
+
+        debug_log("Reclaiming ownership of bind-mounted project files", "info")
+        self._run(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "-v",
+                f"{self.project_dir}:/mnt",
+                RECLAIM_IMAGE,
+                "chown",
+                "-R",
+                f"{uid}:{gid}",
+                "/mnt",
+            ],
+            timeout=CLEANUP_TIMEOUT,
+        )
+
     def cleanup(self) -> None:
         """Tear down services and volumes, ignoring any failure."""
         debug_log("Cleaning up Docker services", "info")
+        self.reclaim_bind_mount_ownership()
         self._run(
-            [COMPOSE_COMMAND, "down", "-v", "--remove-orphans"], timeout=CLEANUP_TIMEOUT
+            [*self.compose_command(), "down", "-v", "--remove-orphans"],
+            timeout=CLEANUP_TIMEOUT,
         )
         self._run(["docker", "system", "prune", "-f"], timeout=STATUS_TIMEOUT)

fastapi_fastkit/backend/inspection/lint.py

@@ -1,12 +1,17 @@
 # --------------------------------------------------------------------------
 # Static analysis of the generated project.
 #
-# ``compileall`` is mandatory - a template that cannot be byte-compiled is
-# broken beyond argument. ``mypy`` is opt-in because it needs the template's
-# own dependencies installed and is far slower.
+# The compile check is mandatory - a template that cannot be compiled is
+# broken beyond argument. It is performed in-process with ``compile()`` and
+# deliberately writes nothing to disk: a Docker test run beforehand can leave
+# root-owned ``__pycache__`` directories in the bind-mounted project, and
+# ``compileall`` would then fail with a PermissionError that says nothing
+# about the template. ``mypy`` is opt-in because it needs the template's own
+# dependencies installed and is far slower.
 #
 # @author bnbong
 # --------------------------------------------------------------------------
+import os
 import subprocess
 import sys
 from typing import List
@@ -15,43 +20,52 @@ from fastapi_fastkit.utils.logging import debug_log
 
 from .context import InspectionContext
 
-COMPILE_TIMEOUT = 120
 MYPY_TIMEOUT = 300
 
+#: Directories never worth compiling - third party code and build artefacts.
+EXCLUDED_DIRS = {".venv", "venv", "__pycache__", "node_modules"}
+
 
 def _interpreter(ctx: InspectionContext) -> str:
     """Prefer the inspection venv interpreter, falling back to the host one."""
     return ctx.python_executable() or sys.executable
 
 
+def _iter_python_files(root: str) -> List[str]:
+    """Collect every ``.py`` file below ``root``, skipping excluded directories."""
+    python_files: List[str] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [name for name in dirnames if name not in EXCLUDED_DIRS]
+        for file_name in sorted(filenames):
+            if file_name.endswith(".py"):
+                python_files.append(os.path.join(dirpath, file_name))
+    return python_files
+
+
 def check_compileall(ctx: InspectionContext) -> bool:
-    """Byte-compile every Python file of the generated project."""
-    command: List[str] = [
-        _interpreter(ctx),
-        "-m",
-        "compileall",
-        "-q",
-        "-x",
-        r"(\.venv|venv|node_modules)",
-        ctx.temp_dir,
-    ]
-    try:
-        result = subprocess.run(
-            command,
-            cwd=ctx.temp_dir,
-            capture_output=True,
-            text=True,
-            timeout=COMPILE_TIMEOUT,
-        )
-    except subprocess.TimeoutExpired:
-        ctx.add_error("compileall timed out")
-        return False
-    except OSError as e:
-        ctx.add_error(f"Failed to run compileall: {e}")
-        return False
+    """Compile every Python file of the generated project, in memory.
 
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip()
+    Nothing is written to disk - no ``__pycache__`` is created - so the check
+    stays a pure syntax gate that cannot trip over file ownership left behind
+    by a containerised test run.
+    """
+    failures: List[str] = []
+
+    for path in _iter_python_files(ctx.temp_dir):
+        try:
+            with open(path, "rb") as f:
+                source = f.read()
+        except OSError as e:
+            failures.append(f"{path}: could not be read ({e})")
+            continue
+
+        try:
+            compile(source, path, "exec", dont_inherit=True)
+        except (SyntaxError, ValueError) as e:
+            failures.append(f"{path}: {e}")
+
+    if failures:
+        detail = "\n".join(failures)
         ctx.add_error(f"Generated project failed to compile:\n{detail}")
         return False
 

fastapi_fastkit/backend/inspection/smoke.py

@@ -115,12 +115,17 @@ def _probe(url: str, timeout: int = 5) -> Optional[int]:
 
 
 def _wait_for_server(
-    process: "subprocess.Popen[bytes]", base_url: str, timeout: int
+    process: Optional["subprocess.Popen[bytes]"], base_url: str, timeout: int
 ) -> Tuple[bool, str]:
-    """Poll ``/docs`` until the server answers, the process dies or time runs out."""
+    """Poll ``/docs`` until the server answers, the process dies or time runs out.
+
+    ``process`` is ``None`` when the server is not ours to watch - a container
+    started by the Docker strategy, for one - in which case only the timeout
+    bounds the wait.
+    """
     deadline = time.time() + timeout
     while time.time() < deadline:
-        if process.poll() is not None:
+        if process is not None and process.poll() is not None:
             return False, "server process exited before becoming reachable"
         status = _probe(f"{base_url}/docs")
         if status is not None:
@@ -228,14 +233,70 @@ def _read_log_tail(log_file: IO[bytes]) -> str:
         return ""
 
 
+def _check_health_endpoint(ctx: InspectionContext, base_url: str) -> Optional[str]:
+    """Probe ``/health``; return a failure message, or ``None`` when acceptable.
+
+    A template without a ``/health`` route answers 404, which is fine; an
+    unreachable endpoint is only worth a warning, but a route that exists and
+    answers with anything other than 200 is a real failure.
+    """
+    health_status = _probe(f"{base_url}/health")
+    if health_status is None:
+        ctx.add_warning("Smoke test: /health did not respond")
+    elif health_status == 404:
+        debug_log("Template exposes no /health endpoint, skipping", "info")
+    elif health_status != 200:
+        return (
+            f"Smoke test failed: /health returned HTTP {health_status} (expected 200)"
+        )
+    return None
+
+
+def run_http_smoke(ctx: InspectionContext, base_url: str) -> bool:
+    """Verify the HTTP surface of a server someone else already started.
+
+    Used by the Docker strategy, which has the real application running in a
+    container: probing its published port is more honest than booting a second
+    copy on the host, and templates that require Docker never get a host venv
+    to boot one with in the first place.
+    """
+    debug_log(f"Running smoke test against {base_url}", "info")
+    reachable, reason = _wait_for_server(None, base_url, ctx.options.smoke_timeout)
+    if not reachable:
+        ctx.add_error(f"Smoke test failed: {reason}")
+        return False
+
+    failure = _check_health_endpoint(ctx, base_url)
+    if failure:
+        ctx.add_error(failure)
+        return False
+
+    debug_log("Smoke test passed", "info")
+    return True
+
+
+def _requires_docker(ctx: InspectionContext) -> bool:
+    """Whether the template declares that it can only run under Docker."""
+    return bool((ctx.template_config or {}).get("requires_docker", False))
+
+
 def check_smoke_test(ctx: InspectionContext) -> bool:
     """Boot the generated project and verify its HTTP surface."""
     if not ctx.options.run_smoke_test:
         debug_log("Smoke test disabled", "info")
         return True
 
+    if ctx.smoke_result is not None:
+        debug_log("Reusing the smoke test result recorded while testing", "info")
+        return ctx.smoke_result
+
     python_executable = ctx.python_executable()
     if not python_executable or not os.path.exists(python_executable):
+        if _requires_docker(ctx):
+            ctx.add_warning(
+                "smoke test skipped: Docker template without published port"
+            )
+            return True
         ctx.add_error(
             "Smoke test requires an installed environment, but no virtual "
             "environment was prepared for the generated project"
@@ -306,16 +367,9 @@ def check_smoke_test(ctx: InspectionContext) -> bool:
                     ctx.add_error(last_failure)
                     return False
 
-                health_status = _probe(f"{base_url}/health")
-                if health_status is None:
-                    ctx.add_warning("Smoke test: /health did not respond")
-                elif health_status == 404:
-                    debug_log("Template exposes no /health endpoint, skipping", "info")
-                elif health_status != 200:
-                    ctx.add_error(
-                        f"Smoke test failed: /health returned HTTP {health_status} "
-                        "(expected 200)\n" + _read_log_tail(log_file)
-                    )
+                failure = _check_health_endpoint(ctx, base_url)
+                if failure:
+                    ctx.add_error(f"{failure}\n{_read_log_tail(log_file)}".rstrip())
                     return False
             finally:
                 _terminate(process)

fastapi_fastkit/backend/inspection/strategies.py

@@ -16,6 +16,7 @@ from typing import Any, Dict, List
 from fastapi_fastkit.backend.main import create_venv, install_dependencies_with_manager
 from fastapi_fastkit.utils.logging import debug_log
 
+from . import smoke
 from .context import InspectionContext
 from .docker import DockerCompose
 from .fsutils import fix_all_script_line_endings, fix_script_line_endings
@@ -278,7 +279,15 @@ class DockerStrategy(TestStrategy):
                 self.ctx.add_error(verification_error)
                 return False
 
-            return self._run_tests(compose)
+            if not self._run_tests(compose):
+                return False
+
+            # The application is running right here, in a container with a
+            # published port: probing that is the only way a Docker-only
+            # template gets a smoke test, since no host venv is ever built for
+            # it. Done before the ``finally`` below tears the stack down.
+            self._run_smoke_test(compose)
+            return True
         except subprocess.TimeoutExpired:
             self.ctx.add_error("Docker Compose setup timed out")
             return False
@@ -307,6 +316,28 @@ class DockerStrategy(TestStrategy):
         debug_log("Docker tests passed successfully", "info")
         return True
 
+    def _run_smoke_test(self, compose: DockerCompose) -> None:
+        """Probe the running container's HTTP surface and record the verdict.
+
+        The result lands on the context so the pipeline's Smoke Test step
+        reuses it instead of trying (and failing) to boot the project from a
+        virtual environment that a Docker run never creates.
+        """
+        if not self.ctx.options.run_smoke_test:
+            return
+
+        port = compose.published_port()
+        if port is None:
+            self.ctx.add_warning(
+                "smoke test skipped: Docker template without published port"
+            )
+            self.ctx.smoke_result = True
+            return
+
+        self.ctx.smoke_result = smoke.run_http_smoke(
+            self.ctx, f"http://127.0.0.1:{port}"
+        )
+
 
 def select_fallback_strategy(ctx: InspectionContext) -> TestStrategy:
     """Pick the fallback strategy, or the standard one when none is configured."""

fastapi_fastkit/backend/main.py

@@ -18,6 +18,7 @@ from fastapi_fastkit.backend.package_managers import PackageManagerFactory
 from fastapi_fastkit.backend.project_builder.preset_layout import (
     app_module_from_main_path,
 )
+from fastapi_fastkit.backend.route_wiring import register_router, router_alias
 from fastapi_fastkit.backend.transducer import (
     copy_and_convert_template,
     copy_and_convert_template_file,
@@ -1464,6 +1465,16 @@ def _handle_api_router_file(
         if os.path.exists(api_source):
             copy_and_convert_template_file(api_source, api_router_file)
 
+        # The __init__ template may be empty; initialize the API router.
+        if os.path.exists(api_router_file):
+            with open(api_router_file, "r", encoding="utf-8") as f:
+                content = f.read()
+            if not content.strip():
+                with open(api_router_file, "w", encoding="utf-8") as f:
+                    f.write(
+                        "from fastapi import APIRouter\n\napi_router = APIRouter()\n"
+                    )
+
     # Update API router to include new route
     if os.path.exists(api_router_file):
         _update_api_router(api_router_file, route_name)
@@ -1484,23 +1495,22 @@ def _update_api_router(api_router_file: str, route_name: str) -> None:
         with open(api_router_file, "r", encoding="utf-8") as f:
             content = f.read()
 
-        route_import = f"from .routes import {route_name}"
+        alias = router_alias(api_router_file, "routes", route_name, route_name)
+        suffix = f" as {alias}" if alias != route_name else ""
+        route_import = f"from .routes import {route_name}{suffix}"
         route_include = (
-            f"api_router.include_router({route_name}.router, "
+            f"api_router.include_router({alias}.router, "
             f'prefix="/{route_name}", tags=["{route_name}"])'
         )
 
-        if (
-            route_import in content
-            and f"api_router.include_router({route_name}.router" in content
-        ):
-            return  # Already included
-
-        content = insert_import_line(content, route_import)
-        content = insert_statement_line(content, route_include)
-
-        with open(api_router_file, "w", encoding="utf-8") as f:
-            f.write(content)
+        register_router(
+            {
+                "api_dir": os.path.dirname(api_router_file),
+                "api_router_file": api_router_file,
+            },
+            route_import,
+            route_include,
+        )
 
         debug_log(f"Updated API router to include {route_name}", "info")
 
@@ -1594,7 +1604,9 @@ def _update_main_app(
         print_warning(f"Failed to update main.py: {e}")
 
 
-def add_new_route(project_dir: str, route_name: str) -> None:
+def add_new_route(
+    project_dir: str, route_name: str, layout: Optional[str] = None
+) -> None:
     """
     Add a new API route to an existing FastAPI project.
 
@@ -1604,37 +1616,20 @@ def add_new_route(project_dir: str, route_name: str) -> None:
 
     :param project_dir: Path to the project directory
     :param route_name: Name of the new route to add
+    :param layout: Explicit route layout, or None to select from preset metadata
     :raises BackendExceptions: If route addition fails
     """
     try:
-        # Setup paths
-        modules_dir = os.path.join(settings.FASTKIT_TEMPLATE_ROOT, "modules")
-        layout = resolve_project_layout(project_dir)
-        src_dir = layout["package_dir"]
-
-        # Ensure project structure exists
-        target_dirs = _ensure_project_structure(src_dir)
-
-        # Create route files
-        _create_route_files(
-            modules_dir, target_dirs, route_name, layout["package_module"]
+        # Import here to avoid a circular import with route_generators.
+        from fastapi_fastkit.backend.route_generators import (
+            get_route_generator,
+            resolve_route_layout,
         )
 
-        # Handle API router file
-        _handle_api_router_file(
-            target_dirs, modules_dir, route_name, layout["api_router_file"]
-        )
-
-        # Process init files
-        module_types = ["api/routes", "crud", "schemas"]
-        _process_init_files(modules_dir, target_dirs, module_types)
-
-        # Update main application
-        _update_main_app(
-            src_dir,
-            route_name,
-            router_module=layout["api_router_module"],
-            main_py_path=layout["main"],
+        route_layout = resolve_route_layout(project_dir, layout)
+        project_layout = resolve_project_layout(project_dir)
+        get_route_generator(route_layout).add_new_route(
+            project_dir, route_name, project_layout
         )
 
         debug_log(f"Successfully added new route: {route_name}", "info")