litestar-vite 0.1.1__py3-none-any.whl → 0.15.0rc2__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,133 @@
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+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``.
+
+    Example::
+
+        from litestar_vite.inertia import InertiaPlugin, InertiaConfig
+
+        app = Litestar(
+            plugins=[InertiaPlugin(InertiaConfig())],
+            middleware=[ServerSideSessionConfig().middleware],
+        )
+    """
+
+    __slots__ = ("_portal", "config")
+
+    def __init__(self, config: "InertiaConfig") -> "None":
+        """Initialize the plugin with Inertia configuration."""
+        self.config = config
+
+    @asynccontextmanager
+    async def lifespan(self, app: "Litestar") -> "AsyncGenerator[None, None]":
+        """Lifespan to ensure the event loop is available.
+
+        Args:
+            app: The :class:`Litestar <litestar.app.Litestar>` instance.
+
+        Yields:
+            An asynchronous context manager.
+        """
+
+        with start_blocking_portal() as portal:
+            self._portal = portal
+            yield
+
+    @property
+    def portal(self) -> "BlockingPortal":
+        """Return the blocking portal used for deferred prop resolution.
+
+        Returns:
+            The BlockingPortal instance.
+        """
+        return self._portal
+
+    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 ImproperlyConfiguredException
+        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)
+        from litestar.exceptions import HTTPException
+
+        app_config.exception_handlers.update(  # pyright: ignore[reportUnknownMemberType]
+            {Exception: exception_to_http_response, HTTPException: exception_to_http_response}
+        )
+        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])
+        app_config.type_encoders = {
+            StaticProp: lambda val: val.render(),
+            DeferredProp: lambda val: val.render(),
+            **(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/request.py

@@ -0,0 +1,286 @@
+from functools import cached_property
+from typing import TYPE_CHECKING, cast
+from urllib.parse import unquote
+
+from litestar import Request
+from litestar.connection.base import AuthT, StateT, UserT, empty_receive, empty_send
+
+from litestar_vite.inertia._utils import InertiaHeaders
+
+if TYPE_CHECKING:
+    from litestar.types import Receive, Scope, Send
+
+    from litestar_vite.inertia.plugin import InertiaPlugin
+
+__all__ = ("InertiaDetails", "InertiaHeaders", "InertiaRequest")
+
+_DEFAULT_COMPONENT_OPT_KEYS: "tuple[str, ...]" = ("component", "page")
+
+
+class InertiaDetails:
+    """InertiaDetails holds all the values sent by Inertia client in headers and provide convenient properties."""
+
+    def __init__(self, request: "Request[UserT, AuthT, StateT]") -> None:
+        """Initialize :class:`InertiaDetails`"""
+        self.request = request
+
+    def _get_header_value(self, name: "InertiaHeaders") -> "str | None":
+        """Parse request header
+
+        Check for uri encoded header and unquotes it in readable format.
+
+        Args:
+            name: The header name.
+
+        Returns:
+            The header value.
+        """
+
+        if value := self.request.headers.get(name.value.lower()):
+            is_uri_encoded = self.request.headers.get(f"{name.value.lower()}-uri-autoencoded") == "true"
+            return unquote(value) if is_uri_encoded else value
+        return None
+
+    def _get_route_component(self) -> "str | None":
+        """Return the route component from handler opts if present.
+
+        Returns:
+            The route component name, or None if not configured on the handler.
+        """
+        rh = self.request.scope.get("route_handler")  # pyright: ignore[reportUnknownMemberType]
+        if rh:
+            component_opt_keys: "tuple[str, ...]" = _DEFAULT_COMPONENT_OPT_KEYS
+            try:
+                inertia_plugin: "InertiaPlugin" = self.request.app.plugins.get("InertiaPlugin")
+                component_opt_keys = inertia_plugin.config.component_opt_keys
+            except KeyError:
+                pass
+
+            for key in component_opt_keys:
+                if (value := rh.opt.get(key)) is not None:
+                    return cast("str", value)
+        return None
+
+    def __bool__(self) -> bool:
+        """Return True when the request is sent by an Inertia client.
+
+        Returns:
+            True if the request originated from an Inertia client, otherwise False.
+        """
+        return self._get_header_value(InertiaHeaders.ENABLED) == "true"
+
+    @cached_property
+    def route_component(self) -> "str | None":
+        """Return the route component name.
+
+        Returns:
+            The route component name, or None if not configured.
+        """
+        return self._get_route_component()
+
+    @cached_property
+    def partial_component(self) -> "str | None":
+        """Return the partial component name from headers.
+
+        Returns:
+            The partial component name, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.PARTIAL_COMPONENT)
+
+    @cached_property
+    def partial_data(self) -> "str | None":
+        """Return partial-data keys requested by the client.
+
+        Returns:
+            Comma-separated partial-data keys, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.PARTIAL_DATA)
+
+    @cached_property
+    def partial_except(self) -> "str | None":
+        """Return partial-except keys requested by the client.
+
+        Returns:
+            Comma-separated partial-except keys, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.PARTIAL_EXCEPT)
+
+    @cached_property
+    def reset_props(self) -> "str | None":
+        """Return comma-separated props to reset on navigation.
+
+        Returns:
+            Comma-separated prop keys to reset, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.RESET)
+
+    @cached_property
+    def error_bag(self) -> "str | None":
+        """Return the error bag name for scoped validation errors.
+
+        Returns:
+            The error bag name, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.ERROR_BAG)
+
+    @cached_property
+    def merge_intent(self) -> "str | None":
+        """Return infinite-scroll merge intent (append/prepend).
+
+        Returns:
+            The merge intent string, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.INFINITE_SCROLL_MERGE_INTENT)
+
+    @cached_property
+    def version(self) -> "str | None":
+        """Return the Inertia asset version sent by the client.
+
+        Returns:
+            The version string, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.VERSION)
+
+    @cached_property
+    def referer(self) -> "str | None":
+        """Return the referer value if present.
+
+        Returns:
+            The referer value, or None if not present.
+        """
+        return self._get_header_value(InertiaHeaders.REFERER)
+
+    @cached_property
+    def is_partial_render(self) -> bool:
+        """Return True when the request is a partial render.
+
+        Returns:
+            True if the request is a partial render, otherwise False.
+        """
+        return bool(self.partial_component == self.route_component and (self.partial_data or self.partial_except))
+
+    @cached_property
+    def partial_keys(self) -> list[str]:
+        """Return parsed partial-data keys.
+
+        Returns:
+            Parsed partial-data keys.
+        """
+        return self.partial_data.split(",") if self.partial_data is not None else []
+
+    @cached_property
+    def partial_except_keys(self) -> list[str]:
+        """Return parsed partial-except keys (takes precedence over partial_keys).
+
+        Returns:
+            Parsed partial-except keys.
+        """
+        return self.partial_except.split(",") if self.partial_except is not None else []
+
+    @cached_property
+    def reset_keys(self) -> list[str]:
+        """Return parsed reset keys from headers.
+
+        Returns:
+            Parsed reset keys.
+        """
+        return self.reset_props.split(",") if self.reset_props is not None else []
+
+
+class InertiaRequest(Request[UserT, AuthT, StateT]):
+    """Inertia Request class to work with Inertia client."""
+
+    __slots__ = ("inertia",)
+
+    def __init__(self, scope: "Scope", receive: "Receive" = empty_receive, send: "Send" = empty_send) -> None:
+        """Initialize :class:`InertiaRequest`"""
+        super().__init__(scope=scope, receive=receive, send=send)
+        self.inertia = InertiaDetails(self)
+
+    @property
+    def is_inertia(self) -> bool:
+        """True if the request contained inertia headers.
+
+        Returns:
+            True if the request contains Inertia headers, otherwise False.
+        """
+        return bool(self.inertia)
+
+    @property
+    def inertia_enabled(self) -> bool:
+        """True if the route handler contains an inertia enabled configuration.
+
+        Returns:
+            True if the route is configured with an Inertia component, otherwise False.
+        """
+        return bool(self.inertia.route_component is not None)
+
+    @property
+    def is_partial_render(self) -> bool:
+        """True if the request is a partial reload.
+
+        Returns:
+            True if the request is a partial reload, otherwise False.
+        """
+        return self.inertia.is_partial_render
+
+    @property
+    def partial_keys(self) -> "set[str]":
+        """Get the props to include in partial render.
+
+        Returns:
+            A set of prop keys to include.
+        """
+        return set(self.inertia.partial_keys)
+
+    @property
+    def partial_except_keys(self) -> "set[str]":
+        """Get the props to exclude from partial render (v2).
+
+        Takes precedence over partial_keys if both present.
+
+        Returns:
+            A set of prop keys to exclude.
+        """
+        return set(self.inertia.partial_except_keys)
+
+    @property
+    def reset_keys(self) -> "set[str]":
+        """Get the props to reset on navigation (v2).
+
+        Returns:
+            A set of prop keys to reset.
+        """
+        return set(self.inertia.reset_keys)
+
+    @property
+    def error_bag(self) -> "str | None":
+        """Get the error bag name for scoped validation errors (v2).
+
+        Returns:
+            The error bag name, or None if not present.
+        """
+        return self.inertia.error_bag
+
+    @property
+    def merge_intent(self) -> "str | None":
+        """Get the infinite scroll merge intent (v2).
+
+        Returns 'append' or 'prepend' for infinite scroll merging.
+
+        Returns:
+            The merge intent string, or None if not present.
+        """
+        return self.inertia.merge_intent
+
+    @property
+    def inertia_version(self) -> "str | None":
+        """Get the Inertia asset version sent by the client.
+
+        The client sends this header so the server can detect version mismatches
+        and trigger a hard refresh when assets have changed.
+
+        Returns:
+            The version string sent by the client, or None if not present.
+        """
+        return self.inertia.version