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

litestar_vite/inertia/_utils.py

@@ -0,0 +1,99 @@
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from litestar_vite.inertia.types import InertiaHeaderType
+
+
+class InertiaHeaders(str, Enum):
+    """Enum for Inertia Headers"""
+
+    ENABLED = "X-Inertia"
+    VERSION = "X-Inertia-Version"
+    PARTIAL_DATA = "X-Inertia-Partial-Data"
+    PARTIAL_COMPONENT = "X-Inertia-Partial-Component"
+    LOCATION = "X-Inertia-Location"
+    REFERER = "Referer"
+
+
+def get_enabled_header(enabled: bool = True) -> "dict[str, Any]":
+    """True if inertia is enabled.
+
+    Args:
+        enabled: Whether inertia is enabled.
+
+    Returns:
+        The headers for inertia.
+    """
+
+    return {InertiaHeaders.ENABLED.value: "true" if enabled else "false"}
+
+
+def get_version_header(version: str) -> "dict[str, Any]":
+    """Return headers for change swap method response.
+
+    Args:
+        version: The version of the inertia.
+
+    Returns:
+        The headers for inertia.
+    """
+    return {InertiaHeaders.VERSION.value: version}
+
+
+def get_partial_data_header(partial: str) -> "dict[str, Any]":
+    """Return headers for a partial data response.
+
+    Args:
+        partial: The partial data.
+
+    Returns:
+        The headers for inertia.
+    """
+    return {InertiaHeaders.PARTIAL_DATA.value: partial}
+
+
+def get_partial_component_header(partial: str) -> "dict[str, Any]":
+    """Return headers for a partial data response.
+
+    Args:
+        partial: The partial data.
+
+    Returns:
+        The headers for inertia.
+    """
+    return {InertiaHeaders.PARTIAL_COMPONENT.value: partial}
+
+
+def get_headers(inertia_headers: "InertiaHeaderType") -> "dict[str, Any]":
+    """Return headers for Inertia responses.
+
+    Args:
+        inertia_headers: The inertia headers.
+
+    Raises:
+        ValueError: If the inertia headers are None.
+
+    Returns:
+        The headers for inertia.
+    """
+    if not inertia_headers:
+        msg = "Value for inertia_headers cannot be None."
+        raise ValueError(msg)
+    inertia_headers_dict: "dict[str, Callable[..., dict[str, Any]]]" = {
+        "enabled": get_enabled_header,
+        "partial_data": get_partial_data_header,
+        "partial_component": get_partial_component_header,
+        "version": get_version_header,
+    }
+
+    header: "dict[str, Any]" = {}
+    response: "dict[str, Any]"
+    key: "str"
+    value: "Any"
+
+    for key, value in inertia_headers.items():
+        if value is not None:
+            response = inertia_headers_dict[key](value)
+            header.update(response)
+    return header

litestar_vite/inertia/config.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+__all__ = ("InertiaConfig",)
+
+
+@dataclass
+class InertiaConfig:
+    """Configuration for InertiaJS support."""
+
+    root_template: str = "index.html"
+    """Name of the root template to use.
+
+    This must be a path that is found by the Vite Plugin template config
+    """
+    component_opt_key: str = "component"
+    """An identifier to use on routes to get the inertia component to render."""
+    exclude_from_js_routes_key: str = "exclude_from_routes"
+    """An identifier to use on routes to exclude a route from the generated routes typescript file."""
+    redirect_unauthorized_to: "Optional[str]" = None
+    """Optionally supply a path where unauthorized requests should redirect."""
+    redirect_404: "Optional[str]" = None
+    """Optionally supply a path where 404 requests should redirect."""
+    extra_static_page_props: "dict[str, Any]" = field(default_factory=dict)
+    """A dictionary of values to automatically add in to page props on every response."""
+    extra_session_page_props: "set[str]" = field(default_factory=set)
+    """A set of session keys for which the value automatically be added (if it exists) to the response."""

litestar_vite/inertia/exception_handler.py

@@ -0,0 +1,131 @@
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+from litestar import MediaType
+from litestar.connection import Request
+from litestar.connection.base import AuthT, StateT, UserT
+from litestar.exceptions import (
+    HTTPException,
+    ImproperlyConfiguredException,
+    InternalServerException,
+    NotAuthorizedException,
+    NotFoundException,
+    PermissionDeniedException,
+)
+from litestar.exceptions.responses import (
+    create_debug_response,  # pyright: ignore[reportUnknownVariableType]
+    create_exception_response,  # pyright: ignore[reportUnknownVariableType]
+)
+from litestar.plugins.flash import flash
+from litestar.repository.exceptions import (
+    ConflictError,  # pyright: ignore[reportUnknownVariableType,reportAttributeAccessIssue]
+    NotFoundError,  # pyright: ignore[reportUnknownVariableType,reportAttributeAccessIssue]
+    RepositoryError,  # pyright: ignore[reportUnknownVariableType,reportAttributeAccessIssue]
+)
+from litestar.response import Response
+from litestar.status_codes import (
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_500_INTERNAL_SERVER_ERROR,
+)
+
+from litestar_vite.inertia.helpers import error
+from litestar_vite.inertia.response import InertiaBack, InertiaRedirect, InertiaResponse
+
+if TYPE_CHECKING:
+    from litestar.connection import Request
+    from litestar.connection.base import AuthT, StateT, UserT
+    from litestar.response import Response
+
+    from litestar_vite.inertia.plugin import InertiaPlugin
+
+FIELD_ERR_RE = re.compile(r"field `(.+)`$")
+
+
+class _HTTPConflictException(HTTPException):
+    """Request conflict with the current state of the target resource."""
+
+    status_code: int = HTTP_409_CONFLICT
+
+
+def exception_to_http_response(request: "Request[UserT, AuthT, StateT]", exc: "Exception") -> "Response[Any]":
+    """Handler for all exceptions subclassed from HTTPException.
+
+    Args:
+        request: The request object.
+        exc: The exception to handle.
+
+    Returns:
+        The response object.
+    """
+    inertia_enabled = getattr(request, "inertia_enabled", False) or getattr(request, "is_inertia", False)
+
+    if not inertia_enabled:
+        if isinstance(exc, NotFoundError):
+            http_exc = NotFoundException
+        elif isinstance(exc, (RepositoryError, ConflictError)):
+            http_exc = _HTTPConflictException  # type: ignore[assignment]
+        else:
+            http_exc = InternalServerException  # type: ignore[assignment]
+        if request.app.debug and http_exc not in {PermissionDeniedException, NotFoundError}:
+            return cast("Response[Any]", create_debug_response(request, exc))
+        return cast("Response[Any]", create_exception_response(request, http_exc(detail=str(exc.__cause__))))  # pyright: ignore[reportUnknownArgumentType]
+    return create_inertia_exception_response(request, exc)
+
+
+def create_inertia_exception_response(request: "Request[UserT, AuthT, StateT]", exc: "Exception") -> "Response[Any]":
+    """Create the inertia exception response.
+
+    Args:
+        request: The request object.
+        exc: The exception to handle.
+
+    Returns:
+        The response object.
+    """
+    is_inertia = getattr(request, "is_inertia", False)
+    status_code = getattr(exc, "status_code", HTTP_500_INTERNAL_SERVER_ERROR)
+    preferred_type = MediaType.HTML if not is_inertia else MediaType.JSON
+    detail = getattr(exc, "detail", "")  # litestar exceptions
+    extras = getattr(exc, "extra", "")  # msgspec exceptions
+    content: dict[str, Any] = {"status_code": status_code, "message": getattr(exc, "detail", "")}
+    inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
+    if extras:
+        content.update({"extra": extras})
+    try:
+        flash(request, detail, category="error")
+    except (AttributeError, ImproperlyConfiguredException):
+        msg = "Unable to set `flash` session state.  A valid session was not found for this request."
+        request.logger.warning(msg)
+    if extras and len(extras) >= 1:
+        message = extras[0]
+        default_field = f"root.{message.get('key')}" if message.get("key", None) is not None else "root"  # type: ignore
+        error_detail = cast("str", message.get("message", detail))  # type: ignore[union-attr] # pyright: ignore[reportUnknownMemberType]
+        match = FIELD_ERR_RE.search(error_detail)
+        field = match.group(1) if match else default_field
+        if isinstance(message, dict):
+            error(request, field, error_detail or detail)
+    if status_code in {HTTP_422_UNPROCESSABLE_ENTITY, HTTP_400_BAD_REQUEST}:
+        return InertiaBack(request)
+    if isinstance(exc, PermissionDeniedException):
+        return InertiaBack(request)
+    if (status_code == HTTP_401_UNAUTHORIZED or isinstance(exc, NotAuthorizedException)) and (
+        inertia_plugin.config.redirect_unauthorized_to is not None
+        and request.url.path != inertia_plugin.config.redirect_unauthorized_to
+    ):
+        return InertiaRedirect(request, redirect_to=inertia_plugin.config.redirect_unauthorized_to)
+
+    if status_code in {HTTP_404_NOT_FOUND, HTTP_405_METHOD_NOT_ALLOWED} and (
+        inertia_plugin.config.redirect_404 is not None and request.url.path != inertia_plugin.config.redirect_404
+    ):
+        return InertiaRedirect(request, redirect_to=inertia_plugin.config.redirect_404)
+
+    return InertiaResponse[Any](
+        media_type=preferred_type,
+        content=content,
+        status_code=status_code,
+    )

litestar_vite/inertia/helpers.py

@@ -0,0 +1,325 @@
+import inspect
+from collections import defaultdict
+from collections.abc import Coroutine, Generator, Iterable, Mapping
+from contextlib import contextmanager
+from functools import lru_cache
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, TypeVar, Union, cast, overload
+
+from anyio.from_thread import BlockingPortal, start_blocking_portal
+from litestar.exceptions import ImproperlyConfiguredException
+from litestar.utils.empty import value_or_default
+from litestar.utils.scope.state import ScopeState
+from markupsafe import Markup
+from typing_extensions import ParamSpec, TypeGuard
+
+if TYPE_CHECKING:
+    from litestar.connection import ASGIConnection
+
+    from litestar_vite.inertia.plugin import InertiaPlugin
+    from litestar_vite.inertia.routes import Routes
+
+T = TypeVar("T")
+T_ParamSpec = ParamSpec("T_ParamSpec")
+PropKeyT = TypeVar("PropKeyT", bound=str)
+StaticT = TypeVar("StaticT", bound=object)
+
+
+@overload
+def lazy(key: str, value_or_callable: "None") -> "StaticProp[str, None]": ...
+
+
+@overload
+def lazy(key: str, value_or_callable: "T") -> "StaticProp[str, T]": ...
+
+
+@overload
+def lazy(key: str, value_or_callable: "Callable[..., None]" = ...) -> "DeferredProp[str, None]": ...
+
+
+@overload
+def lazy(
+    key: str, value_or_callable: "Callable[..., Coroutine[Any, Any, None]]" = ...
+) -> "DeferredProp[str, None]": ...
+
+
+@overload
+def lazy(
+    key: str,
+    value_or_callable: "Callable[..., Union[T, Coroutine[Any, Any, T]]]" = ...,  # pyright: ignore[reportInvalidTypeVarUse]
+) -> "DeferredProp[str, T]": ...
+
+
+def lazy(
+    key: str,
+    value_or_callable: "Optional[Union[T, Callable[..., Coroutine[Any, Any, None]], Callable[..., T], Callable[..., Union[T, Coroutine[Any, Any, T]]]]]" = None,
+) -> "Union[StaticProp[str, None], StaticProp[str, T], DeferredProp[str, T], DeferredProp[str, None]]":
+    """Wrap an async function to return a DeferredProp.
+
+    Args:
+        key: The key to store the value under.
+        value_or_callable: The value or callable to store.
+
+    Returns:
+        The wrapped value or callable.
+    """
+    if value_or_callable is None:
+        return StaticProp[str, None](key=key, value=None)
+
+    if not callable(value_or_callable):
+        return StaticProp[str, T](key=key, value=value_or_callable)
+
+    return DeferredProp[str, T](key=key, value=cast("Callable[..., T | Coroutine[Any, Any, T]]", value_or_callable))
+
+
+class StaticProp(Generic[PropKeyT, StaticT]):
+    """A wrapper for static property evaluation."""
+
+    def __init__(self, key: "PropKeyT", value: "StaticT") -> None:
+        self._key = key
+        self._result = value
+
+    @property
+    def key(self) -> "PropKeyT":
+        return self._key
+
+    def render(self, portal: "Optional[BlockingPortal]" = None) -> "StaticT":
+        return self._result
+
+
+class DeferredProp(Generic[PropKeyT, T]):
+    """A wrapper for deferred property evaluation."""
+
+    def __init__(
+        self, key: "PropKeyT", value: "Optional[Callable[..., Optional[Union[T, Coroutine[Any, Any, T]]]]]" = None
+    ) -> None:
+        self._key = key
+        self._value = value
+        self._evaluated = False
+        self._result: "Optional[T]" = None
+
+    @property
+    def key(self) -> "PropKeyT":
+        return self._key
+
+    @staticmethod
+    @contextmanager
+    def with_portal(portal: "Optional[BlockingPortal]" = None) -> "Generator[BlockingPortal, None, None]":
+        if portal is None:
+            with start_blocking_portal() as p:
+                yield p
+        else:
+            yield portal
+
+    @staticmethod
+    def _is_awaitable(
+        v: "Callable[..., Union[T, Coroutine[Any, Any, T]]]",
+    ) -> "TypeGuard[Coroutine[Any, Any, T]]":
+        return inspect.iscoroutinefunction(v)
+
+    def render(self, portal: "Optional[BlockingPortal]" = None) -> "Union[T, None]":
+        if self._evaluated:
+            return self._result
+        if self._value is None or not callable(self._value):
+            self._result = self._value
+            self._evaluated = True
+            return self._result
+        if not self._is_awaitable(cast("Callable[..., T]", self._value)):
+            self._result = cast("T", self._value())
+            self._evaluated = True
+            return self._result
+        with self.with_portal(portal) as p:
+            self._result = p.call(cast("Callable[..., T]", self._value))
+            self._evaluated = True
+            return self._result
+
+
+def is_lazy_prop(value: "Any") -> "TypeGuard[Union[DeferredProp[Any, Any], StaticProp[Any, Any]]]":
+    """Check if value is a deferred property.
+
+    Args:
+        value: Any value to check
+
+    Returns:
+        bool: True if value is a deferred property
+    """
+    return isinstance(value, (DeferredProp, StaticProp))
+
+
+def should_render(value: "Any", partial_data: "Optional[set[str]]" = None) -> "bool":
+    """Check if value should be rendered.
+
+    Args:
+        value: Any value to check
+        partial_data: Optional set of keys for partial rendering
+
+    Returns:
+        bool: True if value should be rendered
+    """
+    partial_data = partial_data or set()
+    if is_lazy_prop(value):
+        return value.key in partial_data
+    return True
+
+
+def is_or_contains_lazy_prop(value: "Any") -> "bool":
+    """Check if value is or contains a deferred property.
+
+    Args:
+        value: Any value to check
+
+    Returns:
+        bool: True if value is or contains a deferred property
+    """
+    if is_lazy_prop(value):
+        return True
+    if isinstance(value, str):
+        return False
+    if isinstance(value, Mapping):
+        return any(is_or_contains_lazy_prop(v) for v in cast("Mapping[str, Any]", value).values())
+    if isinstance(value, Iterable):
+        return any(is_or_contains_lazy_prop(v) for v in cast("Iterable[Any]", value))
+    return False
+
+
+def lazy_render(
+    value: "T", partial_data: "Optional[set[str]]" = None, portal: "Optional[BlockingPortal]" = None
+) -> "T":
+    """Filter deferred properties from the value based on partial data.
+
+    Args:
+        value: The value to filter
+        partial_data: Keys for partial rendering
+        portal: Optional portal to use for async rendering
+
+    Returns:
+        The filtered value
+    """
+    partial_data = partial_data or set()
+    if isinstance(value, str):
+        return cast("T", value)
+    if isinstance(value, Mapping):
+        return cast(
+            "T",
+            {
+                k: lazy_render(v, partial_data, portal)
+                for k, v in cast("Mapping[str, Any]", value).items()
+                if should_render(v, partial_data)
+            },
+        )
+
+    if isinstance(value, (list, tuple)):
+        filtered = [
+            lazy_render(v, partial_data, portal) for v in cast("Iterable[Any]", value) if should_render(v, partial_data)
+        ]
+        return cast("T", type(value)(filtered))  # pyright: ignore[reportUnknownArgumentType]
+
+    if is_lazy_prop(value) and should_render(value, partial_data):
+        return cast("T", value.render(portal))
+
+    return cast("T", value)
+
+
+def get_shared_props(
+    request: "ASGIConnection[Any, Any, Any, Any]",
+    partial_data: "Optional[set[str]]" = None,
+) -> "dict[str, Any]":
+    """Return shared session props for a request.
+
+    Args:
+        request: The ASGI connection.
+        partial_data: Optional set of keys for partial rendering.
+        portal: Optional portal to use for async rendering
+    Returns:
+        Dict[str, Any]: The shared props.
+
+    Note:
+        Be sure to call this before `self.create_template_context` if you would like to include the `flash` message details.
+    """
+    props: "dict[str, Any]" = {}
+    flash: "dict[str, list[str]]" = defaultdict(list)
+    errors: "dict[str, Any]" = {}
+    error_bag = request.headers.get("X-Inertia-Error-Bag", None)
+
+    try:
+        errors = request.session.pop("_errors", {})
+        shared_props = cast("dict[str,Any]", request.session.pop("_shared", {}))
+        inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
+
+        # Handle deferred props
+        for key, value in shared_props.items():
+            if is_lazy_prop(value) and should_render(value, partial_data):
+                props[key] = value.render(inertia_plugin.portal)
+                continue
+            if should_render(value, partial_data):
+                props[key] = value
+
+        for message in cast("list[dict[str,Any]]", request.session.pop("_messages", [])):
+            flash[message["category"]].append(message["message"])
+
+        props.update(inertia_plugin.config.extra_static_page_props)
+        for session_prop in inertia_plugin.config.extra_session_page_props:
+            if session_prop not in props and session_prop in request.session:
+                props[session_prop] = request.session.get(session_prop)
+
+    except (AttributeError, ImproperlyConfiguredException):
+        msg = "Unable to generate all shared props.  A valid session was not found for this request."
+        request.logger.warning(msg)
+
+    props["flash"] = flash
+    props["errors"] = {error_bag: errors} if error_bag is not None else errors
+    props["csrf_token"] = value_or_default(ScopeState.from_scope(request.scope).csrf_token, "")
+    return props
+
+
+def share(
+    connection: "ASGIConnection[Any, Any, Any, Any]",
+    key: "str",
+    value: "Any",
+) -> "None":
+    """Share a value in the session.
+
+    Args:
+        connection: The ASGI connection.
+        key: The key to store the value under.
+        value: The value to store.
+    """
+    try:
+        connection.session.setdefault("_shared", {}).update({key: value})
+    except (AttributeError, ImproperlyConfiguredException):
+        msg = "Unable to set `share` session state.  A valid session was not found for this request."
+        connection.logger.warning(msg)
+
+
+def error(
+    connection: "ASGIConnection[Any, Any, Any, Any]",
+    key: "str",
+    message: "str",
+) -> "None":
+    """Set an error message in the session.
+
+    Args:
+        connection: The ASGI connection.
+        key: The key to store the error under.
+        message: The error message.
+    """
+    try:
+        connection.session.setdefault("_errors", {}).update({key: message})
+    except (AttributeError, ImproperlyConfiguredException):
+        msg = "Unable to set `error` session state.  A valid session was not found for this request."
+        connection.logger.warning(msg)
+
+
+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>
+        """),
+    )

litestar_vite/inertia/middleware.py

@@ -0,0 +1,49 @@
+from typing import TYPE_CHECKING, Any, Optional
+
+from litestar import Request
+from litestar.middleware import AbstractMiddleware
+from litestar.types import Receive, Scope, Send
+
+from litestar_vite.inertia.response import InertiaRedirect
+from litestar_vite.plugin import VitePlugin
+
+if TYPE_CHECKING:
+    from litestar.connection.base import (
+        AuthT,
+        StateT,
+        UserT,
+    )
+    from litestar.types import ASGIApp, Receive, Scope, Send
+
+
+def redirect_on_asset_version_mismatch(request: "Request[UserT, AuthT, StateT]") -> "Optional[InertiaRedirect]":
+    if getattr(request, "is_inertia", None) is None:
+        return None
+    inertia_version = request.headers.get("X-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 InertiaRedirect(request, redirect_to=str(request.url))
+
+
+class InertiaMiddleware(AbstractMiddleware):
+    def __init__(self, app: "ASGIApp") -> None:
+        super().__init__(app)
+        self.app = app
+
+    async def __call__(
+        self,
+        scope: "Scope",
+        receive: "Receive",
+        send: "Send",
+    ) -> None:
+        request = Request[Any, Any, Any](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)