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

litestar_vite/inertia/middleware.py

@@ -0,0 +1,54 @@
+from typing import TYPE_CHECKING, Any
+
+from litestar.middleware import AbstractMiddleware
+from litestar.types import Receive, Scope, Send
+
+from litestar_vite.inertia.request import InertiaRequest
+from litestar_vite.inertia.response import InertiaExternalRedirect
+from litestar_vite.plugin import VitePlugin
+
+if TYPE_CHECKING:
+    from litestar.types import ASGIApp, Receive, Scope, Send
+
+
+def redirect_on_asset_version_mismatch(request: "InertiaRequest[Any, Any, Any]") -> "InertiaExternalRedirect | None":
+    """Return redirect response when client and server asset versions differ.
+
+    Returns:
+        An InertiaExternalRedirect when versions differ, otherwise None.
+    """
+    if not request.is_inertia:
+        return None
+
+    inertia_version = request.inertia_version
+    if inertia_version is None:
+        return None
+
+    vite_plugin = request.app.plugins.get(VitePlugin)
+    if inertia_version == vite_plugin.asset_loader.version_id:
+        return None
+
+    return InertiaExternalRedirect(request, redirect_to=str(request.url))
+
+
+class InertiaMiddleware(AbstractMiddleware):
+    """Middleware for handling Inertia.js protocol requirements.
+
+    This middleware:
+    1. Detects version mismatches between client and server assets
+    2. Returns 409 Conflict with X-Inertia-Location header when versions differ
+    3. Triggers client-side hard refresh to reload the updated assets
+    """
+
+    def __init__(self, app: "ASGIApp") -> None:
+        super().__init__(app)
+        self.app = app
+
+    async def __call__(self, scope: "Scope", receive: "Receive", send: "Send") -> None:
+        request: InertiaRequest[Any, Any, Any] = InertiaRequest(scope=scope)
+        redirect = redirect_on_asset_version_mismatch(request)
+        if redirect is not None:
+            response = redirect.to_asgi_response(app=None, request=request)  # pyright: ignore[reportUnknownMemberType]
+            await response(scope, receive, send)
+        else:
+            await self.app(scope, receive, send)

litestar_vite/inertia/plugin.py

@@ -0,0 +1,199 @@
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from anyio.from_thread import start_blocking_portal
+from litestar.plugins import InitPluginProtocol
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+    from anyio.from_thread import BlockingPortal
+    from litestar import Litestar
+    from litestar.config.app import AppConfig
+
+    from litestar_vite.config import InertiaConfig
+
+
+class InertiaPlugin(InitPluginProtocol):
+    """Inertia plugin.
+
+    This plugin configures Litestar for Inertia.js support, including:
+    - Session middleware requirement validation
+    - Exception handler for Inertia responses
+    - InertiaRequest and InertiaResponse as default classes
+    - Type encoders for StaticProp and DeferredProp
+
+    BlockingPortal Behavior:
+        The plugin creates a BlockingPortal during its lifespan for executing
+        async DeferredProp callbacks from synchronous type encoders. This is
+        necessary because Litestar's JSON serialization happens synchronously,
+        but DeferredProp may contain async callables.
+
+        The portal is shared across all requests during the app's lifetime.
+        Type encoders for StaticProp and DeferredProp use ``val.render()``
+        which may access this portal for async resolution.
+
+        If you're using DeferredProp outside of InertiaResponse (e.g., in
+        custom serialization), ensure the app lifespan is active and the
+        portal is available via ``inertia_plugin.portal``.
+
+    SSR Client Pooling:
+        When SSR is enabled, the plugin maintains a shared ``httpx.AsyncClient``
+        for all SSR requests. This provides significant performance benefits:
+        - Connection pooling with keep-alive
+        - TLS session reuse
+        - HTTP/2 multiplexing (when available)
+
+        The client is initialized during app lifespan and properly closed on shutdown.
+        Access via ``inertia_plugin.ssr_client`` if needed.
+
+    Example::
+
+        from litestar_vite.inertia import InertiaPlugin, InertiaConfig
+
+        app = Litestar(
+            plugins=[InertiaPlugin(InertiaConfig())],
+            middleware=[ServerSideSessionConfig().middleware],
+        )
+    """
+
+    __slots__ = ("_portal", "_ssr_client", "config")
+
+    def __init__(self, config: "InertiaConfig") -> "None":
+        """Initialize the plugin with Inertia configuration."""
+        self.config = config
+        self._ssr_client: "httpx.AsyncClient | None" = None
+        self._portal: "BlockingPortal | None" = None  # pyright: ignore[reportInvalidTypeForm]
+
+    @asynccontextmanager
+    async def lifespan(self, app: "Litestar") -> "AsyncGenerator[None, None]":
+        """Lifespan to ensure the event loop is available.
+
+        Initializes:
+        - BlockingPortal for sync-to-async DeferredProp resolution
+        - Shared httpx.AsyncClient for SSR requests (connection pooling)
+
+        Args:
+            app: The :class:`Litestar <litestar.app.Litestar>` instance.
+
+        Yields:
+            An asynchronous context manager.
+        """
+        # Initialize shared SSR client with connection pooling
+        # These limits are tuned for typical SSR workloads:
+        # - max_keepalive_connections: 10 per-host keep-alive connections
+        # - max_connections: 20 total concurrent connections
+        # - keepalive_expiry: 30s idle timeout before closing
+        limits = httpx.Limits(max_keepalive_connections=10, max_connections=20, keepalive_expiry=30.0)
+        self._ssr_client = httpx.AsyncClient(
+            limits=limits,
+            timeout=httpx.Timeout(10.0),  # Default timeout, can be overridden per-request
+        )
+
+        try:
+            with start_blocking_portal() as portal:
+                self._portal = portal
+                yield
+        finally:
+            await self._ssr_client.aclose()
+            self._ssr_client = None  # Reset to signal client is closed
+
+    @property
+    def portal(self) -> "BlockingPortal":
+        """Return the blocking portal used for deferred prop resolution.
+
+        Returns:
+            The BlockingPortal instance.
+
+        Raises:
+            RuntimeError: If accessed before app lifespan is active.
+        """
+        if self._portal is None:
+            msg = "BlockingPortal not available. Ensure app lifespan is active."
+            raise RuntimeError(msg)
+        return self._portal
+
+    @property
+    def ssr_client(self) -> "httpx.AsyncClient | None":
+        """Return the shared httpx.AsyncClient for SSR requests.
+
+        The client is initialized during app lifespan and provides connection
+        pooling, TLS session reuse, and HTTP/2 multiplexing benefits.
+
+        Returns:
+            The shared AsyncClient instance, or None if not initialized.
+        """
+        return self._ssr_client
+
+    def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
+        """Configure application for use with Vite.
+
+        Args:
+            app_config: The :class:`AppConfig <litestar.config.app.AppConfig>` instance.
+
+        Raises:
+            ImproperlyConfiguredException: If the Inertia plugin is not properly configured.
+
+        Returns:
+            The :class:`AppConfig <litestar.config.app.AppConfig>` instance.
+        """
+
+        from litestar.exceptions import HTTPException, ImproperlyConfiguredException, ValidationException
+        from litestar.middleware import DefineMiddleware
+        from litestar.middleware.session import SessionMiddleware
+        from litestar.security.session_auth.middleware import MiddlewareWrapper
+        from litestar.utils.predicates import is_class_and_subclass
+
+        from litestar_vite.inertia.exception_handler import exception_to_http_response
+        from litestar_vite.inertia.helpers import DeferredProp, StaticProp
+        from litestar_vite.inertia.middleware import InertiaMiddleware
+        from litestar_vite.inertia.request import InertiaRequest
+        from litestar_vite.inertia.response import InertiaBack, InertiaResponse
+
+        for mw in app_config.middleware:
+            if isinstance(mw, DefineMiddleware) and is_class_and_subclass(
+                mw.middleware, (MiddlewareWrapper, SessionMiddleware)
+            ):
+                break
+        else:
+            msg = "The Inertia plugin require a session middleware."
+            raise ImproperlyConfiguredException(msg)
+
+        # Register exception handlers
+        exception_handlers: "dict[type[Exception] | int, Any]" = {
+            Exception: exception_to_http_response,
+            HTTPException: exception_to_http_response,
+        }
+
+        # Add Precognition exception handler when enabled
+        # Note: The exception handler formats validation errors in Laravel's format.
+        # For successful validation to return 204 (without executing the handler),
+        # use the @precognition decorator on your route handlers.
+        if self.config.precognition:
+            from litestar_vite.inertia.precognition import create_precognition_exception_handler
+
+            exception_handlers[ValidationException] = create_precognition_exception_handler(
+                fallback_handler=exception_to_http_response
+            )
+
+        app_config.exception_handlers.update(exception_handlers)  # pyright: ignore[reportUnknownMemberType]
+        app_config.request_class = InertiaRequest
+        app_config.response_class = InertiaResponse
+        app_config.middleware.append(InertiaMiddleware)
+        app_config.signature_types.extend([InertiaRequest, InertiaResponse, InertiaBack, StaticProp, DeferredProp])
+        # Type encoders for prop resolution
+        # DeferredProp encoder passes the plugin's portal for efficient async resolution
+        # This avoids creating a new BlockingPortal per DeferredProp (~5-10ms savings)
+        app_config.type_encoders = {
+            StaticProp: lambda val: val.render(),
+            DeferredProp: lambda val: val.render(portal=getattr(self, "_portal", None)),
+            **(app_config.type_encoders or {}),
+        }
+        app_config.type_decoders = [
+            (lambda x: x is StaticProp, lambda t, v: t(v)),
+            (lambda x: x is DeferredProp, lambda t, v: t(v)),
+            *(app_config.type_decoders or []),
+        ]
+        app_config.lifespan.append(self.lifespan)  # pyright: ignore[reportUnknownMemberType]
+        return app_config

litestar_vite/inertia/precognition.py

@@ -0,0 +1,274 @@
+"""Precognition support for real-time form validation.
+
+Precognition is a Laravel protocol for running server-side validation without
+executing handler side effects. This module provides Litestar integration.
+
+Usage:
+    1. Enable in config: ``InertiaConfig(precognition=True)``
+    2. Add ``@precognition`` decorator to route handlers
+
+The plugin automatically handles validation failures (422 responses).
+The decorator prevents handler execution on successful validation (204 responses).
+
+See: https://laravel.com/docs/precognition
+
+Note on Rate Limiting:
+    Real-time validation can result in many requests. Laravel has no official
+    rate limiting solution for Precognition. Consider:
+    - Throttling Precognition requests separately from normal requests
+    - Using debounce on the frontend (laravel-precognition libraries do this)
+    - Implementing custom rate limiting that checks for Precognition header
+"""
+
+from functools import wraps
+from typing import TYPE_CHECKING, Any
+
+from litestar import MediaType, Response
+from litestar.exceptions import ValidationException
+from litestar.status_codes import HTTP_204_NO_CONTENT, HTTP_422_UNPROCESSABLE_ENTITY
+
+from litestar_vite.inertia._utils import InertiaHeaders
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from litestar import Request
+
+__all__ = (
+    "PrecognitionResponse",
+    "create_precognition_exception_handler",
+    "normalize_validation_errors",
+    "precognition",
+)
+
+
+def normalize_validation_errors(exc: ValidationException, validate_only: "set[str] | None" = None) -> "dict[str, Any]":
+    """Normalize Litestar validation errors to Laravel format.
+
+    Laravel's Precognition protocol expects errors in this format:
+    ```json
+    {
+        "message": "The given data was invalid.",
+        "errors": {
+            "email": ["The email field is required."],
+            "password": ["The password must be at least 8 characters."]
+        }
+    }
+    ```
+
+    Args:
+        exc: The ValidationException from Litestar.
+        validate_only: If provided, only include errors for these fields.
+            Used for partial field validation as the user types.
+
+    Returns:
+        A dict in Laravel's validation error format.
+    """
+    errors: "dict[str, list[str]]" = {}
+
+    # Litestar's ValidationException.detail can be:
+    # - A string message
+    # - A list of error dicts with 'key', 'message', and 'source'
+    # - Other structured data
+    detail = exc.detail
+
+    if isinstance(detail, list):
+        for error in detail:  # pyright: ignore[reportUnknownVariableType]
+            if isinstance(error, dict):
+                key: str = str(error.get("key", ""))  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
+                message: str = str(error.get("message", str(error)))  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
+                source: str = str(error.get("source", ""))  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
+
+                # Build field name from source and key
+                if source and key:
+                    field_name = f"{source}.{key}" if source != "body" else key
+                elif key:
+                    field_name = key
+                else:
+                    field_name = "_root"
+
+                # Filter by validate_only if specified
+                if validate_only and field_name not in validate_only:
+                    continue
+
+                if field_name not in errors:
+                    errors[field_name] = []
+                errors[field_name].append(message)
+    elif isinstance(detail, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+        errors["_root"] = [detail]
+
+    return {"message": "The given data was invalid.", "errors": errors}
+
+
+class PrecognitionResponse(Response[Any]):
+    """Response for successful Precognition validation.
+
+    Returns 204 No Content with Precognition-Success header.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            content=None, status_code=HTTP_204_NO_CONTENT, headers={InertiaHeaders.PRECOGNITION_SUCCESS.value: "true"}
+        )
+
+
+def create_precognition_exception_handler(
+    *, fallback_handler: "Callable[[Request[Any, Any, Any], ValidationException], Response[Any]] | None" = None
+) -> "Callable[[Request[Any, Any, Any], ValidationException], Response[Any]]":
+    """Create an exception handler for ValidationException that supports Precognition.
+
+    This handler checks if the request is a Precognition request and returns
+    errors in Laravel's format. For non-Precognition requests, it either uses
+    the fallback handler or returns Litestar's default format.
+
+    Args:
+        fallback_handler: Optional handler for non-Precognition requests.
+            If not provided, returns a standard JSON error response.
+
+    Returns:
+        An exception handler function suitable for Litestar's exception_handlers.
+    """
+
+    def handler(request: "Request[Any, Any, Any]", exc: ValidationException) -> "Response[Any]":
+        # Check if this is a Precognition request
+        precognition_header = request.headers.get(InertiaHeaders.PRECOGNITION.value.lower())
+        is_precognition = precognition_header == "true"
+
+        if is_precognition:
+            # Get validate_only fields for partial validation
+            validate_only_header = request.headers.get(InertiaHeaders.PRECOGNITION_VALIDATE_ONLY.value.lower())
+            validate_only = (
+                {field.strip() for field in validate_only_header.split(",") if field.strip()}
+                if validate_only_header
+                else None
+            )
+
+            # Normalize errors to Laravel format
+            error_data = normalize_validation_errors(exc, validate_only)
+
+            # If filtering removed all errors, return success (204)
+            if validate_only and not error_data["errors"]:
+                return PrecognitionResponse()
+
+            return Response(
+                content=error_data,
+                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                media_type=MediaType.JSON,
+                headers={InertiaHeaders.PRECOGNITION.value: "true"},
+            )
+
+        # Non-Precognition request - use fallback or default
+        if fallback_handler is not None:
+            return fallback_handler(request, exc)
+
+        # Default Litestar-style error response
+        return Response(
+            content={
+                "status_code": HTTP_422_UNPROCESSABLE_ENTITY,
+                "detail": "Validation failed",
+                "extra": exc.detail or [],
+            },
+            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+            media_type=MediaType.JSON,
+        )
+
+    return handler
+
+
+def precognition(fn: "Callable[..., Any]") -> "Callable[..., Any]":
+    """Decorator to enable Precognition on a route handler.
+
+    When a Precognition request passes DTO validation, this decorator
+    returns a 204 No Content response instead of executing the handler body.
+    This prevents side effects (database writes, emails, etc.) during validation.
+
+    Args:
+        fn: The route handler function to wrap.
+
+    Returns:
+        A wrapped handler that short-circuits on valid Precognition requests.
+
+    Example:
+        ```python
+        from litestar import post
+        from litestar_vite.inertia import precognition, InertiaRedirect
+
+        @post("/users")
+        @precognition
+        async def create_user(data: UserDTO) -> InertiaRedirect:
+            # This only runs for actual form submissions
+            # Precognition validation requests return 204 automatically
+            user = await User.create(**data.dict())
+            return InertiaRedirect(request, f"/users/{user.id}")
+        ```
+
+    Note:
+        - Validation errors are handled by the exception handler (automatic)
+        - This decorator handles the success case (prevents handler execution)
+        - The decorator checks for Precognition header AFTER DTO validation
+    """
+    import asyncio
+
+    @wraps(fn)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Find the request object in args or kwargs
+        request = _find_request(args, kwargs)  # pyright: ignore[reportUnknownVariableType]
+
+        if request is not None:
+            # Check for Precognition header
+            precognition_header = request.headers.get(InertiaHeaders.PRECOGNITION.value.lower())
+            if precognition_header == "true":
+                # Validation passed (we got here), return success
+                return PrecognitionResponse()
+
+        # Not a Precognition request, run handler normally
+        return fn(*args, **kwargs)
+
+    @wraps(fn)
+    async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Find the request object in args or kwargs
+        request = _find_request(args, kwargs)  # pyright: ignore[reportUnknownVariableType]
+
+        if request is not None:
+            # Check for Precognition header
+            precognition_header = request.headers.get(InertiaHeaders.PRECOGNITION.value.lower())
+            if precognition_header == "true":
+                # Validation passed (we got here), return success
+                return PrecognitionResponse()
+
+        # Not a Precognition request, run handler normally
+        result = fn(*args, **kwargs)
+        if asyncio.iscoroutine(result):
+            return await result
+        return result
+
+    # Return appropriate wrapper based on function type
+    if asyncio.iscoroutinefunction(fn):
+        return async_wrapper
+    return sync_wrapper
+
+
+def _find_request(args: tuple[Any, ...], kwargs: "dict[str, Any]") -> "Request[Any, Any, Any] | None":  # pyright: ignore[reportUnknownParameterType]
+    """Find Request object in function arguments.
+
+    Args:
+        args: Positional arguments to the handler.
+        kwargs: Keyword arguments to the handler.
+
+    Returns:
+        The Request object if found, otherwise None.
+    """
+    from litestar import Request
+
+    # Check kwargs first (named 'request' parameter)
+    if "request" in kwargs:
+        req = kwargs["request"]
+        if isinstance(req, Request):  # pyright: ignore[reportUnknownVariableType]
+            return req  # pyright: ignore[reportUnknownVariableType]
+
+    # Check positional args
+    for arg in args:
+        if isinstance(arg, Request):  # pyright: ignore[reportUnknownVariableType]
+            return arg  # pyright: ignore[reportUnknownVariableType]
+
+    return None