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

litestar_vite/config/_runtime.py

@@ -0,0 +1,235 @@
+"""Runtime execution settings."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+from litestar_vite.config._constants import TRUE_VALUES
+
+__all__ = ("ExternalDevServer", "RuntimeConfig", "resolve_trusted_proxies")
+
+
+def resolve_trusted_proxies() -> "list[str] | str | None":
+    """Resolve trusted_proxies from environment variable.
+
+    Reads LITESTAR_TRUSTED_PROXIES env var. Examples:
+        - "*" -> Trust all proxies (for container environments)
+        - "127.0.0.1" -> Trust localhost only
+        - "10.0.0.0/8,172.16.0.0/12" -> Trust private networks
+
+    Returns:
+        The trusted proxies configuration, or None if not set.
+    """
+    env_value = os.getenv("LITESTAR_TRUSTED_PROXIES")
+    if env_value is None:
+        return None
+    env_value = env_value.strip()
+    if env_value == "*":
+        return "*"
+    if not env_value:
+        return None
+    return [h.strip() for h in env_value.split(",") if h.strip()]
+
+
+def resolve_proxy_mode() -> "Literal['vite', 'direct', 'proxy'] | None":
+    """Resolve proxy_mode from environment variable.
+
+    Reads VITE_PROXY_MODE env var. Valid values:
+    - "vite" (default): Proxy to internal Vite server (allow list - assets only)
+    - "direct": Expose Vite port directly (no proxy)
+    - "proxy": Proxy everything except Litestar routes (deny list)
+    - "none": Disable proxy (for production)
+
+    Raises:
+        ValueError: If an invalid value is provided.
+
+    Returns:
+        The resolved proxy mode, or None if disabled.
+    """
+    env_value = os.getenv("VITE_PROXY_MODE")
+    match env_value.strip().lower() if env_value is not None else None:
+        case None:
+            return "vite"
+        case "none":
+            return None
+        case "direct":
+            return "direct"
+        case "proxy":
+            return "proxy"
+        case "vite":
+            return "vite"
+        case _:
+            msg = f"Invalid VITE_PROXY_MODE: {env_value!r}. Expected one of: vite, direct, proxy, none"
+            raise ValueError(msg)
+
+
+@dataclass
+class ExternalDevServer:
+    """Configuration for external (non-Vite) dev servers.
+
+    Use this when your frontend uses a framework with its own dev server
+    (Angular CLI, Next.js, Create React App, etc.) instead of Vite.
+
+    For SSR frameworks (Astro, Nuxt, SvelteKit) using Vite internally, leave
+    target as None - the proxy will read the dynamic port from the hotfile.
+
+    Attributes:
+        target: The URL of the external dev server (e.g., "http://localhost:4200").
+            If None, the proxy reads the target URL from the Vite hotfile.
+        command: Custom command to start the dev server (e.g., ["ng", "serve"]).
+            If None and start_dev_server=True, uses executor's default start command.
+        build_command: Custom command to build for production (e.g., ["ng", "build"]).
+            If None, uses executor's default build command (e.g., "npm run build").
+        http2: Enable HTTP/2 for proxy connections.
+        enabled: Whether the external proxy is enabled.
+    """
+
+    target: "str | None" = None
+    command: "list[str] | None" = None
+    build_command: "list[str] | None" = None
+    http2: bool = False
+    enabled: bool = True
+
+
+@dataclass
+class RuntimeConfig:
+    """Runtime execution settings.
+
+    Attributes:
+        dev_mode: Enable development mode with HMR/watch.
+        proxy_mode: Proxy handling mode:
+            - "vite" (default): Proxy Vite assets only (allow list - SPA mode)
+            - "direct": Expose Vite port directly (no proxy)
+            - "proxy": Proxy everything except Litestar routes (deny list - framework mode)
+            - None: No proxy (production mode)
+        external_dev_server: Configuration for external dev server (used with proxy_mode="proxy").
+        host: Vite dev server host.
+        port: Vite dev server port.
+        protocol: Protocol for dev server (http/https).
+        executor: JavaScript runtime executor (node, bun, deno).
+        run_command: Custom command to run Vite dev server (auto-detect if None).
+        build_command: Custom command to build with Vite (auto-detect if None).
+        build_watch_command: Custom command for watch mode build.
+        serve_command: Custom command to run production server (for SSR frameworks).
+        install_command: Custom command to install dependencies.
+        is_react: Enable React Fast Refresh support.
+        health_check: Enable health check for dev server startup.
+        detect_nodeenv: Detect and use nodeenv in virtualenv (opt-in).
+        set_environment: Set Vite environment variables from config.
+        set_static_folders: Automatically configure static file serving.
+        csp_nonce: Content Security Policy nonce for inline scripts.
+        spa_handler: Auto-register catch-all SPA route when mode="spa".
+        http2: Enable HTTP/2 for proxy HTTP requests (better multiplexing).
+            WebSocket traffic (HMR) uses a separate connection and is unaffected.
+    """
+
+    dev_mode: bool = field(default_factory=lambda: os.getenv("VITE_DEV_MODE", "False") in TRUE_VALUES)
+    proxy_mode: "Literal['vite', 'direct', 'proxy'] | None" = field(default_factory=resolve_proxy_mode)
+    external_dev_server: "ExternalDevServer | str | None" = None
+    host: str = field(default_factory=lambda: os.getenv("VITE_HOST", "127.0.0.1"))
+    port: int = field(default_factory=lambda: int(os.getenv("VITE_PORT", "5173")))
+    protocol: Literal["http", "https"] = "http"
+    executor: "Literal['node', 'bun', 'deno', 'yarn', 'pnpm'] | None" = None
+    run_command: "list[str] | None" = None
+    build_command: "list[str] | None" = None
+    build_watch_command: "list[str] | None" = None
+    serve_command: "list[str] | None" = None
+    install_command: "list[str] | None" = None
+    is_react: bool = False
+    health_check: bool = field(default_factory=lambda: os.getenv("VITE_HEALTH_CHECK", "False") in TRUE_VALUES)
+    detect_nodeenv: bool = False
+    set_environment: bool = True
+    set_static_folders: bool = True
+    csp_nonce: "str | None" = None
+    spa_handler: bool = True
+    http2: bool = True
+    start_dev_server: bool = True
+    trusted_proxies: "list[str] | str | None" = field(default_factory=resolve_trusted_proxies)
+    """Trusted proxy hosts for X-Forwarded-* header processing.
+
+    When set, the ProxyHeadersMiddleware will read and apply X-Forwarded-Proto,
+    X-Forwarded-For, and X-Forwarded-Host headers only from requests originating
+    from these hosts.
+
+    Accepted values:
+        - None (default): Disabled - do not trust any proxy headers
+        - "*": Trust all proxies (use in controlled environments like Docker/Railway)
+        - List of IP addresses: ["127.0.0.1", "10.0.0.0/8"]
+        - Comma-separated string: "127.0.0.1, 10.0.0.0/8"
+
+    Supports:
+        - IPv4 addresses: "192.168.1.1"
+        - IPv6 addresses: "::1"
+        - CIDR notation: "10.0.0.0/8", "fd00::/8"
+        - Unix socket literals (for advanced setups)
+
+    Security Note:
+        Only enable this when your application is behind a trusted reverse proxy.
+        Never enable in environments where clients can directly connect to the app.
+        Using "*" should only be done in controlled environments where direct client
+        connections are blocked by network configuration.
+
+    Environment Variable: LITESTAR_TRUSTED_PROXIES
+    """
+
+    def __post_init__(self) -> None:
+        """Normalize runtime settings and apply derived defaults."""
+        if isinstance(self.external_dev_server, str):
+            self.external_dev_server = ExternalDevServer(target=self.external_dev_server)
+
+        if self.external_dev_server is not None and self.proxy_mode in {None, "vite"}:
+            self.proxy_mode = "proxy"
+
+        if self.executor is None:
+            self.executor = "node"
+
+        executor_commands = {
+            "node": {
+                "run": ["npm", "run", "dev"],
+                "build": ["npm", "run", "build"],
+                "build_watch": ["npm", "run", "watch"],
+                "serve": ["npm", "run", "serve"],
+                "install": ["npm", "install"],
+            },
+            "bun": {
+                "run": ["bun", "run", "dev"],
+                "build": ["bun", "run", "build"],
+                "build_watch": ["bun", "run", "watch"],
+                "serve": ["bun", "run", "serve"],
+                "install": ["bun", "install"],
+            },
+            "deno": {
+                "run": ["deno", "task", "dev"],
+                "build": ["deno", "task", "build"],
+                "build_watch": ["deno", "task", "watch"],
+                "serve": ["deno", "task", "serve"],
+                "install": ["deno", "install"],
+            },
+            "yarn": {
+                "run": ["yarn", "dev"],
+                "build": ["yarn", "build"],
+                "build_watch": ["yarn", "watch"],
+                "serve": ["yarn", "serve"],
+                "install": ["yarn", "install"],
+            },
+            "pnpm": {
+                "run": ["pnpm", "dev"],
+                "build": ["pnpm", "build"],
+                "build_watch": ["pnpm", "watch"],
+                "serve": ["pnpm", "serve"],
+                "install": ["pnpm", "install"],
+            },
+        }
+
+        if self.executor in executor_commands:
+            cmds = executor_commands[self.executor]
+            if self.run_command is None:
+                self.run_command = cmds["run"]
+            if self.build_command is None:
+                self.build_command = cmds["build"]
+            if self.build_watch_command is None:
+                self.build_watch_command = cmds["build_watch"]
+            if self.serve_command is None:
+                self.serve_command = cmds["serve"]
+            if self.install_command is None:
+                self.install_command = cmds["install"]

litestar_vite/config/_spa.py

@@ -0,0 +1,93 @@
+"""SPA and logging configuration."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+__all__ = ("LoggingConfig", "SPAConfig")
+
+
+@dataclass
+class SPAConfig:
+    """Configuration for SPA HTML transformations.
+
+    This configuration controls how the SPA HTML is transformed before serving,
+    including CSRF token injection.
+
+    Note:
+        Route metadata is now generated as TypeScript (routes.ts) at build time
+        instead of runtime injection. Use TypeGenConfig.generate_routes to enable.
+
+        For Inertia-specific settings like ``use_script_element``, see ``InertiaConfig``.
+
+    Attributes:
+        inject_csrf: Whether to inject CSRF token into HTML (as window.__LITESTAR_CSRF__).
+        csrf_var_name: Global variable name for CSRF token (e.g., window.__LITESTAR_CSRF__).
+        app_selector: CSS selector for the app root element (used for data attributes).
+        cache_transformed_html: Cache transformed HTML in production; disabled when inject_csrf=True because CSRF tokens are per-request.
+    """
+
+    inject_csrf: bool = True
+    csrf_var_name: str = "__LITESTAR_CSRF__"
+    app_selector: str = "#app"
+    cache_transformed_html: bool = True
+
+
+def get_default_log_level() -> "Literal['quiet', 'normal', 'verbose']":
+    """Get default log level from environment variable.
+
+    Checks LITESTAR_VITE_LOG_LEVEL environment variable.
+    Falls back to "normal" if not set or invalid.
+
+    Returns:
+        The log level from environment or "normal" default.
+    """
+    env_level = os.getenv("LITESTAR_VITE_LOG_LEVEL", "").lower()
+    match env_level:
+        case "quiet" | "normal" | "verbose":
+            return env_level
+        case _:
+            return "normal"
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration for console output.
+
+    Controls the verbosity and style of console output from both Python
+    and TypeScript (via .litestar.json bridge).
+
+    Attributes:
+        level: Logging verbosity level.
+            - "quiet": Minimal output (errors only)
+            - "normal": Standard operational messages (default)
+            - "verbose": Detailed debugging information
+            Can also be set via LITESTAR_VITE_LOG_LEVEL environment variable.
+            Precedence: explicit config > env var > default ("normal")
+        show_paths_absolute: Show absolute paths instead of relative paths.
+            Default False shows cleaner relative paths in output.
+        suppress_npm_output: Suppress npm/yarn/pnpm script echo lines.
+            When True, hides lines like "> dev" / "> vite" from output.
+        suppress_vite_banner: Suppress the Vite startup banner.
+            When True, only the LITESTAR banner is shown.
+        timestamps: Include timestamps in log messages.
+
+    Example:
+        Quiet mode for CI/CD::
+
+            ViteConfig(logging=LoggingConfig(level="quiet"))
+
+        Verbose debugging::
+
+            ViteConfig(logging=LoggingConfig(level="verbose", show_paths_absolute=True))
+
+        Environment variable::
+
+            export LITESTAR_VITE_LOG_LEVEL=quiet
+    """
+
+    level: "Literal['quiet', 'normal', 'verbose']" = field(default_factory=get_default_log_level)
+    show_paths_absolute: bool = False
+    suppress_npm_output: bool = False
+    suppress_vite_banner: bool = False
+    timestamps: bool = False

litestar_vite/config/_types.py

@@ -0,0 +1,94 @@
+"""Type generation configuration."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, cast
+
+__all__ = ("TypeGenConfig",)
+
+
+@dataclass
+class TypeGenConfig:
+    """Type generation settings.
+
+    Presence of this config enables type generation. Use ``types=None`` or
+    ``types=False`` in ViteConfig to disable.
+
+    Attributes:
+        output: Output directory for generated types.
+        openapi_path: Path to export OpenAPI schema.
+        routes_path: Path to export routes metadata (JSON format).
+        routes_ts_path: Path to export typed routes TypeScript file.
+        generate_zod: Generate Zod schemas from OpenAPI.
+        generate_sdk: Generate SDK client from OpenAPI.
+        generate_routes: Generate typed routes.ts file (Ziggy-style).
+        generate_page_props: Generate Inertia page props TypeScript file.
+            Auto-enabled when both types and inertia are configured.
+        page_props_path: Path to export page props metadata (JSON format).
+        global_route: Register route() function globally on window object.
+            When True, adds ``window.route = route`` to generated routes.ts,
+            providing global access without imports.
+        fallback_type: Fallback value type for untyped containers in generated Inertia props.
+            Controls whether untyped dict/list become `unknown` (default) or `any`.
+        type_import_paths: Map schema/type names to TypeScript import paths for props types
+            that are not present in OpenAPI (e.g., internal/excluded schemas).
+    """
+
+    output: Path = field(default_factory=lambda: Path("src/generated"))
+    openapi_path: "Path | None" = field(default=None)
+    routes_path: "Path | None" = field(default=None)
+    routes_ts_path: "Path | None" = field(default=None)
+    generate_zod: bool = False
+    generate_sdk: bool = True
+    generate_routes: bool = True
+    generate_page_props: bool = True
+    global_route: bool = False
+    """Register route() function globally on window object.
+
+    When True, the generated routes.ts will include code that registers
+    the type-safe route() function on ``window.route``, similar to Laravel's
+    Ziggy library. This allows using route() without imports:
+
+    .. code-block:: typescript
+
+        // With global_route=True, no import needed:
+        window.route('user-profile', { userId: 123 })
+
+        // TypeScript users should add to global.d.ts:
+        // declare const route: typeof import('@/generated/routes').route
+
+    Default is False to encourage explicit imports for better tree-shaking.
+    """
+    fallback_type: "Literal['unknown', 'any']" = "unknown"
+    type_import_paths: dict[str, str] = field(default_factory=lambda: cast("dict[str, str]", {}))
+    """Map schema/type names to TypeScript import paths for Inertia props.
+
+    Use this for prop types that are not present in OpenAPI (e.g., internal schemas).
+    """
+    page_props_path: "Path | None" = field(default=None)
+    """Path to export page props metadata JSON.
+
+    The Vite plugin reads this file to generate page-props.ts.
+    Defaults to output / "inertia-pages.json".
+    """
+
+    def __post_init__(self) -> None:
+        """Normalize path types and compute defaults based on output directory."""
+        if isinstance(self.output, str):
+            self.output = Path(self.output)
+        if self.openapi_path is None:
+            self.openapi_path = self.output / "openapi.json"
+        elif isinstance(self.openapi_path, str):
+            self.openapi_path = Path(self.openapi_path)
+        if self.routes_path is None:
+            self.routes_path = self.output / "routes.json"
+        elif isinstance(self.routes_path, str):
+            self.routes_path = Path(self.routes_path)
+        if self.routes_ts_path is None:
+            self.routes_ts_path = self.output / "routes.ts"
+        elif isinstance(self.routes_ts_path, str):
+            self.routes_ts_path = Path(self.routes_ts_path)
+        if self.page_props_path is None:
+            self.page_props_path = self.output / "inertia-pages.json"
+        elif isinstance(self.page_props_path, str):
+            self.page_props_path = Path(self.page_props_path)