litestar-vite 0.12.1__py3-none-any.whl → 0.13.1__py3-none-any.whl

litestar_vite/inertia/plugin.py

@@ -0,0 +1,109 @@
+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.inertia.config import InertiaConfig
+
+
+def set_js_routes(app: "Litestar") -> "None":
+    """Generate the route structure of the application on startup."""
+    from litestar_vite.inertia.routes import generate_js_routes
+
+    js_routes = generate_js_routes(app)
+    app.state.js_routes = js_routes
+
+
+class InertiaPlugin(InitPluginProtocol):
+    """Inertia plugin."""
+
+    __slots__ = ("_portal", "config")
+
+    def __init__(self, config: "InertiaConfig") -> "None":
+        """Initialize ``Inertia``.
+
+        Args:
+            config: 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":
+        """Get the portal."""
+        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)
+        app_config.exception_handlers.update({Exception: exception_to_http_response})  # pyright: ignore[reportUnknownMemberType]
+        app_config.request_class = InertiaRequest
+        app_config.response_class = InertiaResponse
+        app_config.middleware.append(InertiaMiddleware)
+        app_config.on_startup.append(set_js_routes)
+        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,154 @@
+from functools import cached_property
+from typing import TYPE_CHECKING, Optional
+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
+
+__all__ = ("InertiaDetails", "InertiaRequest")
+
+
+if TYPE_CHECKING:
+    from litestar.types import Receive, Scope, Send
+
+
+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") -> "Optional[str]":
+        """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) -> "Optional[str]":
+        """Get the route component.
+
+        Checks for the `component` key within the route handler configuration.
+
+        Args:
+            request: The request object.
+
+        Returns:
+            The route component.
+        """
+        rh = self.request.scope.get("route_handler")  # pyright: ignore[reportUnknownMemberType]
+        if rh:
+            return rh.opt.get("component")
+        return None
+
+    def __bool__(self) -> bool:
+        """Check if request is sent by an Inertia client.
+
+        Returns:
+            True if the request is sent by an Inertia client, False otherwise.
+        """
+        return self._get_header_value(InertiaHeaders.ENABLED) == "true"
+
+    @cached_property
+    def route_component(self) -> "Optional[str]":
+        """Get the route component.
+
+        Returns:
+            The route component.
+        """
+        return self._get_route_component()
+
+    @cached_property
+    def partial_component(self) -> "Optional[str]":
+        """Get the partial component.
+
+        Returns:
+            The partial component.
+        """
+        return self._get_header_value(InertiaHeaders.PARTIAL_COMPONENT)
+
+    @cached_property
+    def partial_data(self) -> "Optional[str]":
+        """Get the partial data.
+
+        Returns:
+            The partial data.
+        """
+        return self._get_header_value(InertiaHeaders.PARTIAL_DATA)
+
+    @cached_property
+    def referer(self) -> "Optional[str]":
+        """Get the referer.
+
+        Returns:
+            The referer.
+        """
+        return self._get_header_value(InertiaHeaders.REFERER)
+
+    @cached_property
+    def is_partial_render(self) -> bool:
+        """Check if the request is a partial render.
+
+        Returns:
+            True if the request is a partial render, False otherwise.
+        """
+        return bool(self.partial_component == self.route_component and self.partial_data)
+
+    @cached_property
+    def partial_keys(self) -> list[str]:
+        """Get the partial keys.
+
+        Returns:
+            The partial keys.
+        """
+        return self.partial_data.split(",") if self.partial_data 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."""
+        return bool(self.inertia)
+
+    @property
+    def inertia_enabled(self) -> bool:
+        """True if the route handler contains an inertia enabled configuration."""
+        return bool(self.inertia.route_component is not None)
+
+    @property
+    def is_partial_render(self) -> bool:
+        """True if the route handler contains an inertia enabled configuration."""
+        return self.inertia.is_partial_render
+
+    @property
+    def partial_keys(self) -> "set[str]":
+        """True if the route handler contains an inertia enabled configuration."""
+        return set(self.inertia.partial_keys)

litestar_vite/inertia/response.py

@@ -0,0 +1,321 @@
+import itertools
+from collections.abc import Iterable, Mapping
+from mimetypes import guess_type
+from pathlib import PurePath
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Optional,
+    TypeVar,
+    Union,
+    cast,
+)
+from urllib.parse import quote, urlparse, urlunparse
+
+from litestar import Litestar, MediaType, Request, Response
+from litestar.datastructures.cookie import Cookie
+from litestar.exceptions import ImproperlyConfiguredException
+from litestar.response import Redirect
+from litestar.response.base import ASGIResponse
+from litestar.serialization import get_serializer
+from litestar.status_codes import HTTP_200_OK, HTTP_303_SEE_OTHER, HTTP_307_TEMPORARY_REDIRECT, HTTP_409_CONFLICT
+from litestar.utils.deprecation import warn_deprecation
+from litestar.utils.empty import value_or_default
+from litestar.utils.helpers import get_enum_string_value
+from litestar.utils.scope.state import ScopeState
+
+from litestar_vite.inertia._utils import get_headers
+from litestar_vite.inertia.helpers import (
+    get_shared_props,
+    is_or_contains_lazy_prop,
+    js_routes_script,
+    lazy_render,
+    should_render,
+)
+from litestar_vite.inertia.plugin import InertiaPlugin
+from litestar_vite.inertia.types import InertiaHeaderType, PageProps
+from litestar_vite.plugin import VitePlugin
+
+if TYPE_CHECKING:
+    from litestar.app import Litestar
+    from litestar.background_tasks import BackgroundTask, BackgroundTasks
+    from litestar.connection.base import AuthT, StateT, UserT
+    from litestar.types import ResponseCookies, ResponseHeaders, TypeEncodersMap
+
+
+T = TypeVar("T")
+
+
+class InertiaResponse(Response[T]):
+    """Inertia Response"""
+
+    def __init__(
+        self,
+        content: T,
+        *,
+        template_name: "Optional[str]" = None,
+        template_str: "Optional[str]" = None,
+        background: "Optional[BackgroundTask | BackgroundTasks]" = None,
+        context: "Optional[dict[str, Any]]" = None,
+        cookies: "Optional[ResponseCookies]" = None,
+        encoding: "str" = "utf-8",
+        headers: "Optional[ResponseHeaders]" = None,
+        media_type: "Optional[Union[MediaType, str]]" = None,
+        status_code: "int" = HTTP_200_OK,
+        type_encoders: "Optional[TypeEncodersMap]" = None,
+    ) -> None:
+        """Handle the rendering of a given template into a bytes string.
+
+        Args:
+            content: A value for the response body that will be rendered into bytes string.
+            template_name: Path-like name for the template to be rendered, e.g. ``index.html``.
+            template_str: A string representing the template, e.g. ``tmpl = "Hello <strong>World</strong>"``.
+            background: A :class:`BackgroundTask <.background_tasks.BackgroundTask>` instance or
+                :class:`BackgroundTasks <.background_tasks.BackgroundTasks>` to execute after the response is finished.
+                Defaults to ``None``.
+            context: A dictionary of key/value pairs to be passed to the temple engine's render method.
+            cookies: A list of :class:`Cookie <.datastructures.Cookie>` instances to be set under the response
+                ``Set-Cookie`` header.
+            encoding: Content encoding
+            headers: A string keyed dictionary of response headers. Header keys are insensitive.
+            media_type: A string or member of the :class:`MediaType <.enums.MediaType>` enum. If not set, try to infer
+                the media type based on the template name. If this fails, fall back to ``text/plain``.
+            status_code: A value for the response HTTP status code.
+            type_encoders: A mapping of types to callables that transform them into types supported for serialization.
+
+        Raises:
+            ValueError: If both template_name and template_str are provided.
+        """
+        if template_name and template_str:
+            msg = "Either template_name or template_str must be provided, not both."
+            raise ValueError(msg)
+        self.content = content
+        self.background = background
+        self.cookies: list[Cookie] = (
+            [Cookie(key=key, value=value) for key, value in cookies.items()]
+            if isinstance(cookies, Mapping)
+            else list(cookies or [])
+        )
+        self.encoding = encoding
+        self.headers: dict[str, Any] = (
+            dict(headers) if isinstance(headers, Mapping) else {h.name: h.value for h in headers or {}}
+        )
+        self.media_type = media_type
+        self.status_code = status_code
+        self.response_type_encoders = {**(self.type_encoders or {}), **(type_encoders or {})}
+        self.context = context or {}
+        self.template_name = template_name
+        self.template_str = template_str
+
+    def create_template_context(
+        self,
+        request: "Request[UserT, AuthT, StateT]",
+        page_props: "PageProps[T]",
+        type_encoders: "Optional[TypeEncodersMap]" = None,
+    ) -> "dict[str, Any]":
+        """Create a context object for the template.
+
+        Args:
+            request: A :class:`Request <.connection.Request>` instance.
+            page_props: A formatted object to return the inertia configuration.
+            type_encoders: A mapping of types to callables that transform them into types supported for serialization.
+
+        Returns:
+            A dictionary holding the template context
+        """
+        csrf_token = value_or_default(ScopeState.from_scope(request.scope).csrf_token, "")
+        inertia_props = self.render(page_props, MediaType.JSON, get_serializer(type_encoders)).decode()
+        return {
+            **self.context,
+            "inertia": inertia_props,
+            "js_routes": js_routes_script(request.app.state.js_routes),
+            "request": request,
+            "csrf_input": f'<input type="hidden" name="_csrf_token" value="{csrf_token}" />',
+        }
+
+    def to_asgi_response(  # noqa: C901
+        self,
+        app: "Optional[Litestar]",
+        request: "Request[UserT, AuthT, StateT]",
+        *,
+        background: "Optional[Union[BackgroundTask, BackgroundTasks]]" = None,
+        cookies: "Optional[Iterable[Cookie]]" = None,
+        encoded_headers: "Optional[Iterable[tuple[bytes, bytes]]]" = None,
+        headers: "Optional[dict[str, str]]" = None,
+        is_head_response: "bool" = False,
+        media_type: "Optional[Union[MediaType, str]]" = None,
+        status_code: "Optional[int]" = None,
+        type_encoders: "Optional[TypeEncodersMap]" = None,
+    ) -> "ASGIResponse":
+        if app is not None:
+            warn_deprecation(
+                version="2.1",
+                deprecated_name="app",
+                kind="parameter",
+                removal_in="3.0.0",
+                alternative="request.app",
+            )
+        inertia_enabled = cast(
+            "bool",
+            getattr(request, "inertia_enabled", False) or getattr(request, "is_inertia", False),
+        )
+        is_inertia = cast("bool", getattr(request, "is_inertia", False))
+        headers = {**headers, **self.headers} if headers is not None else self.headers
+        cookies = self.cookies if cookies is None else itertools.chain(self.cookies, cookies)
+        type_encoders = (
+            {**type_encoders, **(self.response_type_encoders or {})} if type_encoders else self.response_type_encoders
+        )
+        if not inertia_enabled:
+            media_type = get_enum_string_value(self.media_type or media_type or MediaType.JSON)
+            return ASGIResponse(
+                background=self.background or background,
+                body=self.render(self.content, media_type, get_serializer(type_encoders)),
+                cookies=cookies,
+                encoded_headers=encoded_headers,
+                encoding=self.encoding,
+                headers=headers,
+                is_head_response=is_head_response,
+                media_type=media_type,
+                status_code=self.status_code or status_code,
+            )
+        is_partial_render = cast("bool", getattr(request, "is_partial_render", False))
+        partial_keys = cast("set[str]", getattr(request, "partial_keys", {}))
+        vite_plugin = request.app.plugins.get(VitePlugin)
+        inertia_plugin = request.app.plugins.get(InertiaPlugin)
+        template_engine = request.app.template_engine  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
+        headers.update(
+            {"Vary": "Accept", **get_headers(InertiaHeaderType(enabled=True))},
+        )
+        shared_props = get_shared_props(
+            request,
+            partial_data=partial_keys if is_partial_render else None,
+        )
+        if is_or_contains_lazy_prop(self.content):
+            filtered_content = lazy_render(
+                self.content,
+                partial_keys if is_partial_render else None,
+                inertia_plugin.portal,
+            )
+            if filtered_content is not None:
+                shared_props["content"] = filtered_content
+        elif should_render(self.content, partial_keys):
+            shared_props["content"] = self.content
+
+        page_props = PageProps[T](
+            component=request.inertia.route_component,  # type: ignore[attr-defined] # pyright: ignore[reportUnknownArgumentType,reportUnknownMemberType,reportAttributeAccessIssue]
+            props=shared_props,  # pyright: ignore[reportArgumentType]
+            version=vite_plugin.asset_loader.version_id,
+            url=request.url.path,
+        )
+        if is_inertia:
+            media_type = get_enum_string_value(self.media_type or media_type or MediaType.JSON)
+            body = self.render(page_props, media_type, get_serializer(type_encoders))
+            return ASGIResponse(  # pyright: ignore[reportUnknownMemberType]
+                background=self.background or background,
+                body=body,
+                cookies=cookies,
+                encoded_headers=encoded_headers,
+                encoding=self.encoding,
+                headers=headers,
+                is_head_response=is_head_response,
+                media_type=media_type,
+                status_code=self.status_code or status_code,
+            )
+
+        if not template_engine:
+            msg = "Template engine is not configured"
+            raise ImproperlyConfiguredException(msg)
+        # it should default to HTML at this point unless the user specified something
+        media_type = media_type or MediaType.HTML
+        if not media_type:
+            if self.template_name:
+                suffixes = PurePath(self.template_name).suffixes
+                for suffix in suffixes:
+                    if _type := guess_type(f"name{suffix}")[0]:
+                        media_type = _type
+                        break
+                else:
+                    media_type = MediaType.TEXT
+            else:
+                media_type = MediaType.HTML
+        context = self.create_template_context(request, page_props, type_encoders)  # pyright: ignore[reportUnknownMemberType]
+        if self.template_str is not None:
+            body = template_engine.render_string(self.template_str, context).encode(self.encoding)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+        else:
+            template_name = self.template_name or inertia_plugin.config.root_template
+            template = template_engine.get_template(template_name)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            body = template.render(**context).encode(self.encoding)  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
+
+        return ASGIResponse(  # pyright: ignore[reportUnknownMemberType]
+            background=self.background or background,
+            body=body,  # pyright: ignore[reportUnknownArgumentType]
+            cookies=cookies,
+            encoded_headers=encoded_headers,
+            encoding=self.encoding,
+            headers=headers,
+            is_head_response=is_head_response,
+            media_type=media_type,
+            status_code=self.status_code or status_code,
+        )
+
+
+class InertiaExternalRedirect(Response[Any]):
+    """Client side redirect."""
+
+    def __init__(
+        self,
+        request: "Request[Any, Any, Any]",
+        redirect_to: "str",
+        **kwargs: "Any",
+    ) -> None:
+        """Initialize external redirect, Set status code to 409 (required by Inertia),
+        and pass redirect url.
+        """
+        super().__init__(
+            content=b"",
+            status_code=HTTP_409_CONFLICT,
+            headers={"X-Inertia-Location": quote(redirect_to, safe="/#%[]=:;$&()+,!?*@'~")},
+            cookies=request.cookies,
+            **kwargs,
+        )
+
+
+class InertiaRedirect(Redirect):
+    """Client side redirect."""
+
+    def __init__(
+        self,
+        request: "Request[Any, Any, Any]",
+        redirect_to: "str",
+        **kwargs: "Any",
+    ) -> None:
+        """Initialize external redirect, Set status code to 409 (required by Inertia),
+        and pass redirect url.
+        """
+        referer = urlparse(request.headers.get("Referer", str(request.base_url)))
+        redirect_to = urlunparse(urlparse(redirect_to)._replace(scheme=referer.scheme))
+        super().__init__(  # pyright: ignore[reportUnknownMemberType]
+            path=redirect_to,
+            status_code=HTTP_307_TEMPORARY_REDIRECT if request.method == "GET" else HTTP_303_SEE_OTHER,
+            cookies=request.cookies,
+            **kwargs,
+        )
+
+
+class InertiaBack(Redirect):
+    """Client side redirect."""
+
+    def __init__(
+        self,
+        request: "Request[Any, Any, Any]",
+        **kwargs: "Any",
+    ) -> None:
+        """Initialize external redirect, Set status code to 409 (required by Inertia),
+        and pass redirect url.
+        """
+        super().__init__(  # pyright: ignore[reportUnknownMemberType]
+            path=request.headers.get("Referer", str(request.base_url)),
+            status_code=HTTP_307_TEMPORARY_REDIRECT if request.method == "GET" else HTTP_303_SEE_OTHER,
+            cookies=request.cookies,
+            **kwargs,
+        )

litestar_vite/inertia/routes.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, Optional
+
+from litestar.app import DEFAULT_OPENAPI_CONFIG
+from litestar.cli._utils import (
+    remove_default_schema_routes,  # pyright: ignore[reportPrivateImportUsage]
+    remove_routes_with_patterns,  # pyright: ignore[reportPrivateImportUsage]
+)
+from litestar.routes import ASGIRoute, WebSocketRoute
+from litestar.serialization import encode_json
+
+if TYPE_CHECKING:
+    from litestar import Litestar
+
+
+@dataclass(frozen=True)
+class Routes:
+    routes: dict[str, str]
+
+    @cached_property
+    def formatted_routes(self) -> str:
+        return encode_json(self.routes).decode(encoding="utf-8")
+
+
+EXCLUDED_METHODS = {"HEAD", "OPTIONS", "TRACE"}
+
+
+def generate_js_routes(
+    app: "Litestar",
+    exclude: "Optional[tuple[str, ...]]" = None,
+    schema: "bool" = False,
+) -> "Routes":
+    sorted_routes = sorted(app.routes, key=lambda r: r.path)
+    if not schema:
+        openapi_config = app.openapi_config or DEFAULT_OPENAPI_CONFIG
+        sorted_routes = remove_default_schema_routes(sorted_routes, openapi_config)
+    if exclude is not None:
+        sorted_routes = remove_routes_with_patterns(sorted_routes, exclude)
+    route_list: dict[str, str] = {}
+    for route in sorted_routes:
+        if isinstance(route, (ASGIRoute, WebSocketRoute)):
+            route_name = route.route_handler.name or route.route_handler.handler_name
+            if len(route.methods.difference(EXCLUDED_METHODS)) > 0:
+                route_list[route_name] = route.path
+        else:
+            for handler in route.route_handlers:
+                route_name = handler.name or handler.handler_name
+                if handler.http_methods.isdisjoint(EXCLUDED_METHODS):
+                    route_list[route_name] = route.path
+
+    return Routes(routes=route_list)

litestar_vite/inertia/types.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, TypedDict, TypeVar
+
+__all__ = (
+    "InertiaHeaderType",
+    "PageProps",
+)
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class PageProps(Generic[T]):
+    """Inertia Page Props Type."""
+
+    component: str
+    url: str
+    version: str
+    props: dict[str, Any]
+
+
+@dataclass
+class InertiaProps(Generic[T]):
+    """Inertia Props Type."""
+
+    page: PageProps[T]
+
+
+class InertiaHeaderType(TypedDict, total=False):
+    """Type for inertia_headers parameter in get_headers()."""
+
+    enabled: "Optional[bool]"
+    version: "Optional[str]"
+    location: "Optional[str]"
+    partial_data: "Optional[str]"
+    partial_component: "Optional[str]"