litestar-vite 0.1.21__py3-none-any.whl → 0.2.0__py3-none-any.whl

litestar_vite/inertia/request.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+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) -> str | None:
+        """Parse request header
+
+        Check for uri encoded header and unquotes it in readable format.
+        """
+
+        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:
+        """Get the route component.
+
+        Checks for the `component` key within the route  configuration.
+        """
+        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."""
+        return self._get_header_value(InertiaHeaders.ENABLED) == "true"
+
+    @cached_property
+    def route_component(self) -> str | None:
+        """Partial Data Reload."""
+        return self._get_route_component()
+
+    @cached_property
+    def partial_component(self) -> str | None:
+        """Partial Data Reload."""
+        return self._get_header_value(InertiaHeaders.PARTIAL_COMPONENT)
+
+    @cached_property
+    def partial_data(self) -> str | None:
+        """Partial Data Reload."""
+        return self._get_header_value(InertiaHeaders.PARTIAL_DATA)
+
+    @cached_property
+    def is_partial_render(self) -> bool:
+        """Is Partial Data Reload."""
+        return bool(self.partial_component == self.route_component and self.partial_data)
+
+    @cached_property
+    def partial_keys(self) -> list[str]:
+        """Is Partial Data Reload."""
+        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__ = (
+        "_json",
+        "_form",
+        "_body",
+        "_msgpack",
+        "_content_type",
+        "_accept",
+        "is_connected",
+        "supports_push_promise",
+        "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)

litestar_vite/inertia/response.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+import itertools
+from collections import defaultdict
+from functools import lru_cache
+from mimetypes import guess_type
+from pathlib import PurePath
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any, Dict, Iterable, Mapping, TypeVar, cast
+from urllib.parse import quote
+
+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 markupsafe import Markup
+
+from litestar_vite.inertia._utils import get_headers
+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 import ASGIConnection
+    from litestar.connection.base import AuthT, StateT, UserT
+    from litestar.types import ResponseCookies, ResponseHeaders, TypeEncodersMap
+
+    from litestar_vite.inertia.routes import Routes
+
+    from .plugin import InertiaPlugin
+
+T = TypeVar("T")
+
+
+def share(
+    connection: ASGIConnection[Any, Any, Any, Any],
+    key: str,
+    value: Any,
+) -> None:
+    connection.session.setdefault("_shared", {}).update({key: value})
+
+
+def error(
+    connection: ASGIConnection[Any, Any, Any, Any],
+    key: str,
+    message: str,
+) -> None:
+    connection.session.setdefault("_errors", {}).update({key: message})
+
+
+def get_shared_props(request: ASGIConnection[Any, Any, Any, Any]) -> Dict[str, Any]:  # noqa: UP006
+    """Return shared session props for a request
+
+
+    Be sure to call this before `self.create_template_context` if you would like to include the `flash` message details.
+    """
+    error_bag = request.headers.get("X-Inertia-Error-Bag", None)
+    errors = request.session.pop("_errors", {})
+    props = request.session.pop("_shared", {})
+    flash: dict[str, list[str]] = defaultdict(list)
+    for message in request.session.pop("_messages", []):
+        flash[message["category"]].append(message["message"])
+
+    inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
+    props.update(inertia_plugin.config.extra_page_props)
+    props["csrf_token"] = value_or_default(ScopeState.from_scope(request.scope).csrf_token, "")
+    props["flash"] = flash
+    props["errors"] = {error_bag: errors} if error_bag is not None else errors
+    return props
+
+
+def js_routes_script(js_routes: Routes) -> Markup:
+    @lru_cache
+    def _markup_safe_json_dumps(js_routes: str) -> Markup:
+        js = js_routes.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026").replace("'", "\\u0027")
+        return Markup(js)
+
+    return Markup(
+        dedent(f"""
+        <script type="module">
+        globalThis.routes = JSON.parse('{_markup_safe_json_dumps(js_routes.formatted_routes)}')
+        </script>
+        """),
+    )
+
+
+class InertiaResponse(Response[T]):
+    """Inertia Response"""
+
+    def __init__(
+        self,
+        content: T,
+        *,
+        template_name: str | None = None,
+        template_str: str | None = None,
+        background: BackgroundTask | BackgroundTasks | None = None,
+        context: dict[str, Any] | None = None,
+        cookies: ResponseCookies | None = None,
+        encoding: str = "utf-8",
+        headers: ResponseHeaders | None = None,
+        media_type: MediaType | str | None = None,
+        status_code: int = HTTP_200_OK,
+        type_encoders: TypeEncodersMap | None = 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.
+        """
+        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: TypeEncodersMap | None = 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(
+        self,
+        app: Litestar | None,
+        request: Request[UserT, AuthT, StateT],
+        *,
+        background: BackgroundTask | BackgroundTasks | None = None,
+        cookies: Iterable[Cookie] | None = None,
+        encoded_headers: Iterable[tuple[bytes, bytes]] | None = None,
+        headers: dict[str, str] | None = None,
+        is_head_response: bool = False,
+        media_type: MediaType | str | None = None,
+        status_code: int | None = None,
+        type_encoders: TypeEncodersMap | None = 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 = getattr(request, "inertia_enabled", False) or getattr(request, "is_inertia", False)
+        is_inertia = 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,
+            )
+        vite_plugin = request.app.plugins.get(VitePlugin)
+        template_engine = vite_plugin.template_config.to_engine()
+        headers.update(
+            {"Vary": "Accept", **get_headers(InertiaHeaderType(enabled=True))},
+        )
+        shared_props = get_shared_props(request)
+        page_props = PageProps[T](
+            component=request.inertia.route_component,  # type: ignore[attr-defined] # pyright: ignore[reportUnknownArgumentType,reportUnknownMemberType,reportAttributeAccessIssue]
+            props={"content": self.content, **shared_props},  # pyright: ignore[reportArgumentType]
+            version=template_engine.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(
+                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)
+        else:
+            inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
+            template_name = self.template_name or inertia_plugin.config.root_template
+            # cast to str b/c we know that either template_name cannot be None if template_str is None
+            template = template_engine.get_template(template_name)
+            body = template.render(**context).encode(self.encoding)
+
+        return ASGIResponse(
+            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,
+        )
+
+
+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=kwargs.get("content", ""),
+            status_code=HTTP_409_CONFLICT,
+            headers={"X-Inertia": "true", "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.
+        """
+        super().__init__(
+            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__(
+            path=request.headers["Referer"],
+            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,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from litestar.app import DEFAULT_OPENAPI_CONFIG
+from litestar.cli._utils import (
+    remove_default_schema_routes,
+    remove_routes_with_patterns,
+)
+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: tuple[str, ...] | None = 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,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, 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: bool | None
+    version: str | None
+    location: str | None
+    partial_data: str | None
+    partial_component: str | None