litestar-vite 0.15.0__py3-none-any.whl → 0.15.0rc2__py3-none-any.whl

litestar_vite/plugin/__init__.py

@@ -1,687 +0,0 @@
-"""Vite Plugin for Litestar.
-
-This module provides the VitePlugin class for integrating Vite with Litestar.
-The plugin handles:
-
-- Static file serving configuration
-- Jinja2 template callable registration
-- Vite dev server process management
-- Async asset loader initialization
-- Development proxies for Vite HTTP and HMR WebSockets (with hop-by-hop header filtering)
-
-Example::
-
-    from litestar import Litestar
-    from litestar_vite import VitePlugin, ViteConfig
-
-    app = Litestar(
-        plugins=[VitePlugin(config=ViteConfig(dev_mode=True))],
-    )
-"""
-
-import os
-from contextlib import asynccontextmanager, contextmanager
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-import httpx
-from litestar.exceptions import NotFoundException
-from litestar.middleware import DefineMiddleware
-from litestar.plugins import CLIPlugin, InitPluginProtocol
-from litestar.static_files import create_static_files_router  # pyright: ignore[reportUnknownVariableType]
-
-from litestar_vite.config import JINJA_INSTALLED, TRUE_VALUES, ExternalDevServer
-from litestar_vite.loader import ViteAssetLoader
-from litestar_vite.plugin._process import ViteProcess
-from litestar_vite.plugin._proxy import ViteProxyMiddleware, create_ssr_proxy_controller, create_vite_hmr_handler
-from litestar_vite.plugin._proxy_headers import ProxyHeadersMiddleware, TrustedHosts
-from litestar_vite.plugin._static import StaticFilesConfig
-from litestar_vite.plugin._utils import (
-    create_proxy_client,
-    get_litestar_route_prefixes,
-    is_litestar_route,
-    is_non_serving_assets_cli,
-    log_fail,
-    log_info,
-    log_success,
-    log_warn,
-    pick_free_port,
-    resolve_litestar_version,
-    set_app_environment,
-    set_environment,
-    static_not_found_handler,
-    vite_not_found_handler,
-)
-
-if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator
-
-    from click import Group
-    from litestar import Litestar
-    from litestar.config.app import AppConfig
-    from litestar.types import ExceptionHandlersMap
-
-    from litestar_vite.config import ViteConfig
-    from litestar_vite.handler import AppHandler
-
-
-class VitePlugin(InitPluginProtocol, CLIPlugin):
-    """Vite plugin for Litestar.
-
-    This plugin integrates Vite with Litestar, providing:
-
-    - Static file serving configuration
-    - Jinja2 template callables for asset tags
-    - Vite dev server process management
-    - Async asset loader initialization
-
-    Example::
-
-        from litestar import Litestar
-        from litestar_vite import VitePlugin, ViteConfig
-
-        app = Litestar(
-            plugins=[
-                VitePlugin(config=ViteConfig(dev_mode=True))
-            ],
-        )
-    """
-
-    __slots__ = (
-        "_asset_loader",
-        "_config",
-        "_proxy_client",
-        "_proxy_target",
-        "_spa_handler",
-        "_static_files_config",
-        "_vite_process",
-    )
-
-    def __init__(
-        self,
-        config: "ViteConfig | None" = None,
-        asset_loader: "ViteAssetLoader | None" = None,
-        static_files_config: "StaticFilesConfig | None" = None,
-    ) -> None:
-        """Initialize the Vite plugin.
-
-        Args:
-            config: Vite configuration. Defaults to ViteConfig() if not provided.
-            asset_loader: Optional pre-initialized asset loader.
-            static_files_config: Optional configuration for static file serving.
-        """
-        from litestar_vite.config import ViteConfig
-
-        if config is None:
-            config = ViteConfig()
-        self._config = config
-        self._asset_loader = asset_loader
-        self._vite_process = ViteProcess(executor=config.executor)
-        self._static_files_config: dict[str, Any] = static_files_config.__dict__ if static_files_config else {}
-        self._proxy_target: "str | None" = None
-        self._proxy_client: "httpx.AsyncClient | None" = None
-        self._spa_handler: "AppHandler | None" = None
-
-    @property
-    def config(self) -> "ViteConfig":
-        """Get the Vite configuration.
-
-        Returns:
-            The ViteConfig instance.
-        """
-        return self._config
-
-    @property
-    def asset_loader(self) -> "ViteAssetLoader":
-        """Get the asset loader instance.
-
-        Lazily initializes the loader if not already set.
-
-        Returns:
-            The ViteAssetLoader instance.
-        """
-
-        if self._asset_loader is None:
-            self._asset_loader = ViteAssetLoader.initialize_loader(config=self._config)
-        return self._asset_loader
-
-    @property
-    def spa_handler(self) -> "AppHandler | None":
-        """Return the configured SPA handler when SPA mode is enabled.
-
-        Returns:
-            The AppHandler instance, or None when SPA mode is disabled/not configured.
-        """
-        return self._spa_handler
-
-    @property
-    def proxy_client(self) -> "httpx.AsyncClient | None":
-        """Return the shared httpx.AsyncClient for proxy requests.
-
-        The client is initialized during app lifespan (dev mode only) and provides
-        connection pooling, TLS session reuse, and HTTP/2 multiplexing benefits.
-
-        Returns:
-            The shared AsyncClient instance, or None if not initialized or not in dev mode.
-        """
-        return self._proxy_client
-
-    def _resolve_bundle_dir(self) -> Path:
-        """Resolve the bundle directory to an absolute path.
-
-        Returns:
-            The absolute path to the bundle directory.
-        """
-        bundle_dir = Path(self._config.bundle_dir)
-        if not bundle_dir.is_absolute():
-            return self._config.root_dir / bundle_dir
-        return bundle_dir
-
-    def _resolve_hotfile_path(self) -> Path:
-        """Resolve the path to the hotfile.
-
-        Returns:
-            The absolute path to the hotfile.
-        """
-        return self._resolve_bundle_dir() / self._config.hot_file
-
-    def _write_hotfile(self, content: str) -> None:
-        """Write content to the hotfile.
-
-        Args:
-            content: The content to write (usually the dev server URL).
-        """
-        hotfile_path = self._resolve_hotfile_path()
-        hotfile_path.parent.mkdir(parents=True, exist_ok=True)
-        hotfile_path.write_text(content, encoding="utf-8")
-
-    def _resolve_dev_command(self) -> "list[str]":
-        """Resolve the command to run for the dev server.
-
-        Returns:
-            The list of command arguments.
-        """
-        ext = self._config.runtime.external_dev_server
-        if isinstance(ext, ExternalDevServer) and ext.enabled:
-            command = ext.command or self._config.executor.start_command
-            log_info(f"Starting external dev server: {' '.join(command)}")
-            return command
-
-        if self._config.hot_reload:
-            log_info("Starting Vite dev server (HMR enabled)")
-            return self._config.run_command
-
-        log_info("Starting Vite watch build process")
-        return self._config.build_watch_command
-
-    def _ensure_proxy_target(self) -> None:
-        """Prepare proxy target URL and port for proxy modes (vite, proxy, ssr).
-
-        For all proxy modes in dev mode:
-        - Auto-selects a free port if VITE_PORT is not explicitly set
-        - Sets the port in runtime config for JS integrations to read
-
-        For 'vite' mode specifically:
-        - Forces loopback host unless VITE_ALLOW_REMOTE is set
-        - Sets _proxy_target directly (JS writes hotfile when server starts)
-
-        For 'proxy'/'ssr' modes:
-        - Port is written to .litestar.json for SSR framework to read
-        - SSR framework writes hotfile with actual URL when ready
-        - Proxy discovers target from hotfile at request time
-        """
-        if not self._config.is_dev_mode:
-            return
-
-        if self._config.proxy_mode is None:
-            return
-
-        if os.getenv("VITE_PORT") is None and self._config.runtime.port == 5173:
-            self._config.runtime.port = pick_free_port()
-
-        if self._config.proxy_mode == "vite":
-            if self._proxy_target is not None:
-                return
-            if os.getenv("VITE_ALLOW_REMOTE", "False") not in TRUE_VALUES:
-                self._config.runtime.host = "127.0.0.1"
-            self._proxy_target = f"{self._config.protocol}://{self._config.host}:{self._config.port}"
-
-    def _configure_inertia(self, app_config: "AppConfig") -> "AppConfig":
-        """Configure Inertia.js by registering an InertiaPlugin instance.
-
-        This is called automatically when `inertia` config is provided to ViteConfig.
-        Users can still use InertiaPlugin manually for more control.
-
-        Args:
-            app_config: The Litestar application configuration.
-
-        Returns:
-            The modified application configuration.
-        """
-        from litestar_vite.inertia.plugin import InertiaPlugin
-
-        inertia_plugin = InertiaPlugin(config=self._config.inertia)  # type: ignore[arg-type]
-        app_config.plugins.append(inertia_plugin)
-
-        return app_config
-
-    def on_cli_init(self, cli: "Group") -> None:
-        """Register CLI commands.
-
-        Args:
-            cli: The Click command group to add commands to.
-        """
-        from litestar_vite.cli import vite_group
-
-        cli.add_command(vite_group)
-
-    def _configure_jinja_callables(self, app_config: "AppConfig") -> None:
-        """Register Jinja2 template callables for Vite asset handling.
-
-        Args:
-            app_config: The Litestar application configuration.
-        """
-        from litestar.contrib.jinja import JinjaTemplateEngine
-
-        from litestar_vite.loader import render_asset_tag, render_hmr_client, render_routes, render_static_asset
-
-        template_config = app_config.template_config  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
-        if template_config and isinstance(
-            template_config.engine_instance,  # pyright: ignore[reportUnknownMemberType]
-            JinjaTemplateEngine,
-        ):
-            engine = template_config.engine_instance  # pyright: ignore[reportUnknownMemberType]
-            engine.register_template_callable(key="vite_hmr", template_callable=render_hmr_client)
-            engine.register_template_callable(key="vite", template_callable=render_asset_tag)
-            engine.register_template_callable(key="vite_static", template_callable=render_static_asset)
-            engine.register_template_callable(key="vite_routes", template_callable=render_routes)
-
-    def _configure_static_files(self, app_config: "AppConfig") -> None:
-        """Configure static file serving for Vite assets.
-
-        The static files router serves real files (JS, CSS, images). SPA fallback (serving
-        index.html for client-side routes) is handled by the AppHandler.
-
-        Args:
-            app_config: The Litestar application configuration.
-        """
-        bundle_dir = self._resolve_bundle_dir()
-
-        resource_dir = Path(self._config.resource_dir)
-        if not resource_dir.is_absolute():
-            resource_dir = self._config.root_dir / resource_dir
-
-        static_dir = Path(self._config.static_dir)
-        if not static_dir.is_absolute():
-            static_dir = self._config.root_dir / static_dir
-
-        static_dirs = [bundle_dir, resource_dir]
-        if static_dir.exists() and static_dir != bundle_dir:
-            static_dirs.append(static_dir)
-
-        opt: dict[str, Any] = {}
-        if self._config.exclude_static_from_auth:
-            opt["exclude_from_auth"] = True
-        user_opt = self._static_files_config.get("opt", {})
-        if user_opt:
-            opt = {**opt, **user_opt}
-
-        base_config: dict[str, Any] = {
-            "directories": (static_dirs if self._config.is_dev_mode else [bundle_dir]),
-            "path": self._config.asset_url,
-            "name": "vite",
-            "html_mode": False,
-            "include_in_schema": False,
-            "opt": opt,
-            "exception_handlers": {NotFoundException: static_not_found_handler},
-        }
-        user_config = {k: v for k, v in self._static_files_config.items() if k != "opt"}
-        static_files_config: dict[str, Any] = {**base_config, **user_config}
-        app_config.route_handlers.append(create_static_files_router(**static_files_config))
-
-    def _configure_dev_proxy(self, app_config: "AppConfig") -> None:
-        """Configure dev proxy middleware and handlers based on proxy_mode.
-
-        Args:
-            app_config: The Litestar application configuration.
-        """
-        proxy_mode = self._config.proxy_mode
-        hotfile_path = self._resolve_hotfile_path()
-
-        if proxy_mode == "vite":
-            self._configure_vite_proxy(app_config, hotfile_path)
-        elif proxy_mode == "proxy":
-            self._configure_ssr_proxy(app_config, hotfile_path)
-
-    def _configure_vite_proxy(self, app_config: "AppConfig", hotfile_path: Path) -> None:
-        """Configure Vite proxy mode (allow list).
-
-        Args:
-            app_config: The Litestar application configuration.
-            hotfile_path: Path to the hotfile.
-        """
-        self._ensure_proxy_target()
-        app_config.middleware.append(
-            DefineMiddleware(
-                ViteProxyMiddleware,
-                hotfile_path=hotfile_path,
-                asset_url=self._config.asset_url,
-                resource_dir=self._config.resource_dir,
-                bundle_dir=self._config.bundle_dir,
-                root_dir=self._config.root_dir,
-                http2=self._config.http2,
-                plugin=self,
-            )
-        )
-        hmr_path = f"{self._config.asset_url.rstrip('/')}/vite-hmr"
-        app_config.route_handlers.append(
-            create_vite_hmr_handler(hotfile_path=hotfile_path, hmr_path=hmr_path, asset_url=self._config.asset_url)
-        )
-
-    def _configure_ssr_proxy(self, app_config: "AppConfig", hotfile_path: Path) -> None:
-        """Configure SSR proxy mode (deny list).
-
-        Args:
-            app_config: The Litestar application configuration.
-            hotfile_path: Path to the hotfile.
-        """
-        self._ensure_proxy_target()
-        external = self._config.external_dev_server
-        static_target = external.target if external else None
-
-        app_config.route_handlers.append(
-            create_ssr_proxy_controller(
-                target=static_target,
-                hotfile_path=hotfile_path if static_target is None else None,
-                http2=external.http2 if external else True,
-                plugin=self,
-            )
-        )
-        hmr_path = f"{self._config.asset_url.rstrip('/')}/vite-hmr"
-        app_config.route_handlers.append(
-            create_vite_hmr_handler(hotfile_path=hotfile_path, hmr_path=hmr_path, asset_url=self._config.asset_url)
-        )
-
-    def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
-        """Configure the Litestar application for Vite.
-
-        This method wires up supporting configuration for dev/prod operation:
-
-        - Adds types used by generated handlers to the signature namespace.
-        - Ensures a consistent NotFound handler for asset/proxy lookups.
-        - Registers optional Inertia and Jinja integrations.
-        - Configures static file routing when enabled.
-        - Configures dev proxy middleware based on proxy_mode.
-        - Creates/initializes the SPA handler where applicable and registers lifespans.
-
-        Args:
-            app_config: The Litestar application configuration.
-
-        Returns:
-            The modified application configuration.
-        """
-        from litestar import Response
-        from litestar.connection import Request as LitestarRequest
-
-        app_config.signature_namespace["Response"] = Response
-        app_config.signature_namespace["Request"] = LitestarRequest
-
-        # Register proxy headers middleware FIRST if configured
-        # This must run before other middleware to ensure correct scheme/client in scope
-        if self._config.trusted_proxies is not None:
-            from litestar_vite.plugin._proxy_headers import ProxyHeadersMiddleware
-
-            app_config.middleware.insert(
-                0,  # Insert at beginning for early processing
-                DefineMiddleware(ProxyHeadersMiddleware, trusted_hosts=self._config.trusted_proxies),
-            )
-
-        handlers: ExceptionHandlersMap = cast("ExceptionHandlersMap", app_config.exception_handlers or {})  # pyright: ignore
-        if NotFoundException not in handlers:
-            handlers[NotFoundException] = vite_not_found_handler
-            app_config.exception_handlers = handlers  # pyright: ignore[reportUnknownMemberType]
-
-        if self._config.inertia is not None:
-            app_config = self._configure_inertia(app_config)
-
-        if JINJA_INSTALLED and self._config.mode in {"template", "htmx"}:
-            self._configure_jinja_callables(app_config)
-
-        skip_static = self._config.mode == "external" and self._config.is_dev_mode
-        if self._config.set_static_folders and not skip_static:
-            self._configure_static_files(app_config)
-
-        if self._config.is_dev_mode and self._config.proxy_mode is not None and not is_non_serving_assets_cli():
-            self._configure_dev_proxy(app_config)
-
-        use_spa_handler = self._config.spa_handler and self._config.mode in {"spa", "framework"}
-        use_spa_handler = use_spa_handler or (self._config.mode == "external" and not self._config.is_dev_mode)
-        if use_spa_handler:
-            from litestar_vite.handler import AppHandler
-
-            self._spa_handler = AppHandler(self._config)
-            app_config.route_handlers.append(self._spa_handler.create_route_handler())
-        elif self._config.mode == "hybrid":
-            from litestar_vite.handler import AppHandler
-
-            self._spa_handler = AppHandler(self._config)
-
-        app_config.lifespan.append(self.lifespan)  # pyright: ignore[reportUnknownMemberType]
-
-        return app_config
-
-    def _check_health(self) -> None:
-        """Check if the Vite dev server is running and ready.
-
-        Polls the dev server URL for up to 5 seconds.
-        """
-        import time
-
-        url = f"{self._config.protocol}://{self._config.host}:{self._config.port}/__vite_ping"
-        for _ in range(50):
-            try:
-                httpx.get(url, timeout=0.1)
-            except httpx.HTTPError:
-                time.sleep(0.1)
-            else:
-                log_success("Vite dev server responded to health check")
-                return
-        log_fail("Vite server health check failed")
-
-    def _run_health_check(self) -> None:
-        """Run the appropriate health check based on proxy mode."""
-        match self._config.proxy_mode:
-            case "proxy":
-                self._check_ssr_health(self._resolve_hotfile_path())
-            case _:
-                self._check_health()
-
-    def _check_ssr_health(self, hotfile_path: Path, timeout: float = 10.0) -> bool:
-        """Wait for SSR framework to be ready via hotfile.
-
-        Polls intelligently for the hotfile and validates HTTP connectivity.
-        Exits early as soon as the server is confirmed ready.
-
-        Args:
-            hotfile_path: Path to the hotfile written by the SSR framework.
-            timeout: Maximum time to wait in seconds (default 10s).
-
-        Returns:
-            True if SSR server is ready, False if timeout reached.
-        """
-        import time
-
-        start = time.time()
-        last_url = None
-
-        while time.time() - start < timeout:
-            if hotfile_path.exists():
-                try:
-                    url = hotfile_path.read_text(encoding="utf-8").strip()
-                    if url:
-                        last_url = url
-                        resp = httpx.get(url, timeout=0.5, follow_redirects=True)
-                        if resp.status_code < 500:
-                            log_success(f"SSR server ready at {url}")
-                            return True
-                except OSError:
-                    pass
-                except httpx.HTTPError:
-                    pass
-
-            time.sleep(0.1)
-
-        if last_url:
-            log_fail(f"SSR server at {last_url} did not respond within {timeout}s")
-        else:
-            log_fail(f"SSR hotfile not found at {hotfile_path} within {timeout}s")
-        return False
-
-    def _export_types_sync(self, app: "Litestar") -> None:
-        """Export type metadata synchronously on startup.
-
-        This exports OpenAPI schema, route metadata (JSON), typed routes (TypeScript),
-        and Inertia pages metadata when type generation is enabled. The Vite plugin
-        watches these files and triggers @hey-api/openapi-ts when they change.
-
-        Uses the shared `export_integration_assets` function to guarantee
-        byte-identical output between CLI and plugin.
-
-        Args:
-            app: The Litestar application instance.
-        """
-        from litestar_vite.codegen import export_integration_assets
-
-        try:
-            result = export_integration_assets(app, self._config)
-
-            if result.exported_files:
-                log_success(f"Types exported → {', '.join(result.exported_files)}")
-        except (OSError, TypeError, ValueError, ImportError) as e:  # pragma: no cover
-            log_warn(f"Type export failed: {e}")
-
-    @contextmanager
-    def server_lifespan(self, app: "Litestar") -> "Iterator[None]":
-        """Server-level lifespan context manager (runs ONCE per server, before workers).
-
-        This is called by Litestar CLI before workers start. It handles:
-        - Environment variable setup (with logging)
-        - Vite dev server process start/stop (ONE instance for all workers)
-        - Type export on startup
-
-        Note: SPA handler and asset loader initialization happens in the per-worker
-        `lifespan` method, which is auto-registered in `on_app_init`.
-
-        Hotfile behavior: the hotfile is written before starting the dev server to ensure proxy
-        middleware and SPA handlers can resolve a target URL immediately on first request.
-
-        Args:
-            app: The Litestar application instance.
-
-        Yields:
-            None
-        """
-        if self._config.is_dev_mode:
-            self._ensure_proxy_target()
-
-        if self._config.set_environment:
-            set_environment(config=self._config)
-            set_app_environment(app)
-            log_info("Applied Vite environment variables")
-
-        self._export_types_sync(app)
-
-        if self._config.is_dev_mode and self._config.runtime.start_dev_server:
-            ext = self._config.runtime.external_dev_server
-            is_external = isinstance(ext, ExternalDevServer) and ext.enabled
-
-            command_to_run = self._resolve_dev_command()
-            if is_external and isinstance(ext, ExternalDevServer) and ext.target:
-                self._write_hotfile(ext.target)
-            elif not is_external:
-                target_url = f"{self._config.protocol}://{self._config.host}:{self._config.port}"
-                self._write_hotfile(target_url)
-
-            try:
-                self._vite_process.start(command_to_run, self._config.root_dir)
-                log_success("Dev server process started")
-                if self._config.health_check and not is_external:
-                    self._run_health_check()
-                yield
-            finally:
-                self._vite_process.stop()
-                log_info("Dev server process stopped.")
-        else:
-            yield
-
-    @asynccontextmanager
-    async def lifespan(self, app: "Litestar") -> "AsyncIterator[None]":
-        """Worker-level lifespan context manager (runs per worker process).
-
-        This is auto-registered in `on_app_init` and handles per-worker initialization:
-        - Environment variable setup (silently - each worker needs process-local env vars)
-        - Shared proxy client initialization (dev mode only, for ViteProxyMiddleware/SSRProxyController)
-        - Asset loader initialization
-        - SPA handler initialization
-        - Route metadata injection
-
-        Note: The Vite dev server process is started in `server_lifespan`, which
-        runs ONCE per server before workers start.
-
-        Args:
-            app: The Litestar application instance.
-
-        Yields:
-            None
-        """
-        from litestar_vite.loader import ViteAssetLoader
-
-        if self._config.set_environment:
-            set_environment(config=self._config)
-            set_app_environment(app)
-
-        # Initialize shared proxy client for ViteProxyMiddleware/SSRProxyController
-        # Uses connection pooling for better performance (HTTP/2 multiplexing, TLS reuse)
-        if self._config.is_dev_mode and self._config.proxy_mode is not None:
-            self._proxy_client = create_proxy_client(http2=self._config.http2)
-
-        if self._asset_loader is None:
-            self._asset_loader = ViteAssetLoader(config=self._config)
-        await self._asset_loader.initialize()
-
-        if self._spa_handler is not None and not self._spa_handler.is_initialized:
-            self._spa_handler.initialize_sync(vite_url=self._proxy_target)
-            log_success("SPA handler initialized")
-
-        is_ssr_mode = self._config.mode == "framework" or self._config.proxy_mode == "proxy"
-        if not self._config.is_dev_mode and not self._config.has_built_assets() and not is_ssr_mode:
-            log_warn(
-                "Vite dev server is disabled (dev_mode=False) but no index.html was found. "
-                "Run your front-end build or set VITE_DEV_MODE=1 to enable HMR."
-            )
-
-        try:
-            yield
-        finally:
-            if self._proxy_client is not None:
-                await self._proxy_client.aclose()
-                self._proxy_client = None
-            if self._spa_handler is not None:
-                await self._spa_handler.shutdown_async()
-
-
-__all__ = (
-    "ProxyHeadersMiddleware",
-    "StaticFilesConfig",
-    "TrustedHosts",
-    "VitePlugin",
-    "ViteProcess",
-    "ViteProxyMiddleware",
-    "create_ssr_proxy_controller",
-    "create_vite_hmr_handler",
-    "get_litestar_route_prefixes",
-    "is_litestar_route",
-    "resolve_litestar_version",
-    "set_app_environment",
-    "set_environment",
-)