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

litestar_vite/__init__.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+from litestar_vite import inertia
 from litestar_vite.config import ViteConfig, ViteTemplateConfig
 from litestar_vite.loader import ViteAssetLoader
 from litestar_vite.plugin import VitePlugin
 from litestar_vite.template_engine import ViteTemplateEngine
 
-__all__ = ("ViteConfig", "ViteTemplateConfig", "VitePlugin", "ViteAssetLoader", "ViteTemplateEngine")
+__all__ = ("ViteConfig", "ViteTemplateConfig", "VitePlugin", "ViteAssetLoader", "ViteTemplateEngine", "inertia")

litestar_vite/cli.py

@@ -122,7 +122,7 @@ def vite_init(
         ctx.obj.app.debug = True
     env: LitestarEnv = ctx.obj
     plugin = env.app.plugins.get(VitePlugin)
-    config = plugin._config
+    config = plugin._config  # pyright: ignore[reportPrivateUsage]
 
     console.rule("[yellow]Initializing Vite[/]", align="left")
     resource_path = Path(resource_path or config.resource_dir)
@@ -144,6 +144,8 @@ def vite_init(
             console.print("Skipping Vite initialization")
             sys.exit(2)
     for output_path in (bundle_path, resource_path, root_path):
+        if output_path.exists():
+            console.print(f" * Creating {output_path!s}")
         output_path.mkdir(parents=True, exist_ok=True)
 
     enable_ssr = (
@@ -277,3 +279,46 @@ def vite_serve(app: Litestar, verbose: bool) -> None:
     command_to_run = plugin.config.run_command if plugin.config.hot_reload else plugin.config.build_watch_command
     execute_command(command_to_run=command_to_run, cwd=plugin.config.root_dir)
     console.print("[yellow]Vite process stopped.[/]")
+
+
+@vite_group.command(
+    name="generate-routes",
+    help="Generate a JSON file with the route configuration",
+)
+@option(
+    "--output",
+    help="output file path",
+    type=ClickPath(dir_okay=False, path_type=Path),
+    default=Path("routes.json"),
+    show_default=True,
+)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+def generate_js_routes(app: Litestar, output: Path, verbose: bool) -> None:
+    """Run vite serve."""
+    import msgspec
+    from litestar.cli._utils import (
+        LitestarCLIException,
+        console,
+    )
+    from litestar.serialization import encode_json, get_serializer
+
+    from litestar_vite.plugin import VitePlugin, set_environment
+
+    if verbose:
+        app.debug = True
+    serializer = get_serializer(app.type_encoders)
+    plugin = app.plugins.get(VitePlugin)
+    if plugin.config.set_environment:
+        set_environment(config=plugin.config)
+    content = msgspec.json.format(
+        encode_json(app.openapi_schema.to_schema(), serializer=serializer),
+        indent=4,
+    )
+
+    try:
+        output.write_bytes(content)
+    except OSError as e:  # pragma: no cover
+        msg = f"failed to write schema to path {output}"
+        raise LitestarCLIException(msg) from e
+
+    console.print("[yellow]Vite process stopped.[/]")

litestar_vite/commands.py

@@ -9,16 +9,15 @@ if TYPE_CHECKING:
     from jinja2 import Environment, Template
     from litestar import Litestar
 
-VITE_INIT_TEMPLATES_PATH = f"{Path(__file__).parent}/templates"
 VITE_INIT_TEMPLATES: set[str] = {"package.json.j2", "tsconfig.json.j2", "vite.config.ts.j2"}
-DEFAULT_RESOURCES: set[str] = {"styles.css", "main.ts"}
+DEFAULT_RESOURCES: set[str] = {"styles.css.j2", "main.ts.j2"}
 DEFAULT_DEV_DEPENDENCIES: dict[str, str] = {
     "typescript": "^5.3.3",
-    "vite": "^5.0.6",
-    "litestar-vite-plugin": "^0.5.1",
-    "@types/node": "^20.10.3",
+    "vite": "^5.3.3",
+    "litestar-vite-plugin": "^0.6.2",
+    "@types/node": "^20.14.10",
 }
-DEFAULT_DEPENDENCIES: dict[str, str] = {"axios": "^1.6.2"}
+DEFAULT_DEPENDENCIES: dict[str, str] = {"axios": "^1.7.2"}
 
 
 def to_json(value: Any) -> str:
@@ -50,10 +49,11 @@ def init_vite(
     """Initialize a new vite project."""
     from jinja2 import Environment, FileSystemLoader, select_autoescape
     from litestar.cli._utils import console
+    from litestar.utils import module_loader
 
-    entry_point: list[str] = []
+    template_path = module_loader.module_to_os_path("litestar_vite.templates")
     vite_template_env = Environment(
-        loader=FileSystemLoader([VITE_INIT_TEMPLATES_PATH]),
+        loader=FileSystemLoader([template_path]),
         autoescape=select_autoescape(),
     )
 
@@ -65,25 +65,24 @@ def init_vite(
         template_name: get_template(environment=vite_template_env, name=template_name)
         for template_name in enabled_templates
     }
-    entry_point = [
-        str(Path(resource_path / resource_name).relative_to(Path.cwd().absolute()))
-        for resource_name in enabled_resources
-    ]
     for template_name, template in templates.items():
-        target_file_name = template_name.removesuffix(".j2")
+        target_file_name = template_name[:-3] if template_name.endswith(".j2") else template_name
         with Path(target_file_name).open(mode="w") as file:
-            console.print(f" * Writing {target_file_name} to {Path(target_file_name).absolute()}")
+            console.print(f" * Writing {target_file_name} to {Path(target_file_name)!s}")
 
             file.write(
                 template.render(
-                    entry_point=entry_point,
+                    entry_point=[
+                        f"{resource_path!s}/{resource_name[:-3] if resource_name.endswith('.j2') else resource_name}"
+                        for resource_name in enabled_resources
+                    ],
                     enable_ssr=enable_ssr,
                     asset_url=asset_url,
-                    root_path=str(root_path.relative_to(Path.cwd().absolute())),
+                    root_path=root_path,
                     resource_path=str(resource_path.relative_to(root_path)),
                     public_path=str(public_path.relative_to(root_path)),
                     bundle_path=str(bundle_path.relative_to(root_path)),
-                    hot_file=str(hot_file.relative_to(Path.cwd().absolute())),
+                    hot_file=str(hot_file.relative_to(root_path)),
                     vite_port=str(vite_port),
                     litestar_port=litestar_port,
                     dependencies=to_json(dependencies),
@@ -92,8 +91,13 @@ def init_vite(
             )
 
     for resource_name in enabled_resources:
-        with Path(resource_path / resource_name).open(mode="w") as file:
-            console.print(f" * Writing {resource_name} to {Path(resource_path / resource_name).absolute()}")
+        template = get_template(environment=vite_template_env, name=resource_name)
+        target_file_name = f"{resource_path}/{resource_name[:-3] if resource_name.endswith('.j2') else resource_name}"
+        with Path(target_file_name).open(mode="w") as file:
+            console.print(
+                f" * Writing {resource_name[:-3] if resource_name.endswith('.j2') else resource_name} to {Path(target_file_name)!s}",
+            )
+            file.write(template.render())
     console.print("[yellow]Vite initialization completed.[/]")
 
 

litestar_vite/config.py

@@ -5,22 +5,18 @@ from dataclasses import dataclass, field
 from functools import cached_property
 from inspect import isclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 from litestar.exceptions import ImproperlyConfiguredException
-from litestar.template import TemplateEngineProtocol
-
-__all__ = ["ViteConfig", "ViteTemplateConfig"]
-
+from litestar.template import TemplateConfig, TemplateEngineProtocol
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
     from litestar.types import PathType
 
-    from litestar_vite.template_engine import ViteTemplateEngine
-
-T = TypeVar("T", bound=TemplateEngineProtocol)
+__all__ = ("ViteConfig", "ViteTemplateConfig")
+EngineType = TypeVar("EngineType", bound=TemplateEngineProtocol[Any, Any])
 
 
 @dataclass
@@ -42,7 +38,7 @@ class ViteConfig:
 
     In a standalone Vue or React application, this would be equivalent to the ``./src`` directory.
     """
-    template_dir: Path | str | None = field(default=None)
+    template_dir: Path | str | None = field(default="templates")
     """Location of the Jinja2 template file."""
     public_dir: Path | str = field(default="public")
     """The optional public directory Vite serves assets from.
@@ -116,7 +112,7 @@ class ViteConfig:
             self.root_dir = Path(self.root_dir)
         if self.template_dir is not None and isinstance(self.template_dir, str):
             self.template_dir = Path(self.template_dir)
-        if self.public_dir is not None and isinstance(self.public_dir, str):
+        if self.public_dir and isinstance(self.public_dir, str):
             self.public_dir = Path(self.public_dir)
         if isinstance(self.resource_dir, str):
             self.resource_dir = Path(self.resource_dir)
@@ -127,7 +123,7 @@ class ViteConfig:
 
 
 @dataclass
-class ViteTemplateConfig(Generic[T]):
+class ViteTemplateConfig(TemplateConfig[EngineType]):
     """Configuration for Templating.
 
     To enable templating, pass an instance of this class to the
@@ -135,34 +131,43 @@ class ViteTemplateConfig(Generic[T]):
     'template_config' key.
     """
 
-    engine: type[ViteTemplateEngine]
+    config: ViteConfig = field(default_factory=lambda: ViteConfig())
+    """A a config for the vite engine`."""
+    engine: type[EngineType] | EngineType | None = field(default=None)
     """A template engine adhering to the :class:`TemplateEngineProtocol
     <litestar.template.base.TemplateEngineProtocol>`."""
-    config: ViteConfig
-    """A a config for the vite engine`."""
-    directory: PathType | None = field(default=None)
+    directory: PathType | list[PathType] | None = field(default=None)
     """A directory or list of directories from which to serve templates."""
-    engine_callback: Callable[[T], None] | None = field(default=None)
+    engine_callback: Callable[[EngineType], None] | None = field(default=None)
     """A callback function that allows modifying the instantiated templating
     protocol."""
 
+    instance: EngineType | None = field(default=None)
+    """An instance of the templating protocol."""
+
     def __post_init__(self) -> None:
         """Ensure that directory is set if engine is a class."""
-        if isclass(self.engine) and not self.directory:
+        if isclass(self.engine) and not self.directory:  # pyright: ignore[reportUnknownMemberType]
             msg = "directory is a required kwarg when passing a template engine class"
             raise ImproperlyConfiguredException(msg)
+        """Ensure that directory is not set if instance is."""
+        if self.instance is not None and self.directory is not None:  # pyright: ignore[reportUnknownMemberType]
+            msg = "directory cannot be set if instance is"
+            raise ImproperlyConfiguredException(msg)
 
-    def to_engine(self) -> T:
+    def to_engine(self) -> EngineType:
         """Instantiate the template engine."""
         template_engine = cast(
-            "T",
-            self.engine(directory=self.directory, config=self.config) if isclass(self.engine) else self.engine,
+            "EngineType",
+            self.engine(directory=self.directory, config=self.config, engine_instance=None)  # pyright: ignore[reportUnknownMemberType,reportCallIssue]
+            if isclass(self.engine)
+            else self.engine,
         )
         if callable(self.engine_callback):
             self.engine_callback(template_engine)
         return template_engine
 
     @cached_property
-    def engine_instance(self) -> T:
+    def engine_instance(self) -> EngineType:
         """Return the template engine instance."""
-        return self.to_engine()
+        return self.to_engine() if self.instance is None else self.instance

litestar_vite/inertia/__init__.py

@@ -0,0 +1,31 @@
+from .config import InertiaConfig
+from .middleware import InertiaMiddleware
+from .plugin import InertiaPlugin
+from .request import InertiaDetails, InertiaHeaders, InertiaRequest
+from .response import (
+    InertiaBack,
+    InertiaExternalRedirect,
+    InertiaRedirect,
+    InertiaResponse,
+    error,
+    get_shared_props,
+    share,
+)
+from .routes import generate_js_routes
+
+__all__ = (
+    "InertiaConfig",
+    "InertiaDetails",
+    "InertiaHeaders",
+    "InertiaRequest",
+    "InertiaResponse",
+    "InertiaExternalRedirect",
+    "InertiaPlugin",
+    "InertiaBack",
+    "share",
+    "error",
+    "get_shared_props",
+    "InertiaRedirect",
+    "generate_js_routes",
+    "InertiaMiddleware",
+)

litestar_vite/inertia/_utils.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+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"
+
+
+def get_enabled_header(enabled: bool = True) -> dict[str, Any]:
+    """True if inertia is enabled."""
+
+    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."""
+    return {InertiaHeaders.VERSION.value: version}
+
+
+def get_partial_data_header(partial: str) -> dict[str, Any]:
+    """Return headers for a partial data response."""
+    return {InertiaHeaders.PARTIAL_DATA.value: partial}
+
+
+def get_partial_component_header(partial: str) -> dict[str, Any]:
+    """Return headers for a partial data response."""
+    return {InertiaHeaders.PARTIAL_COMPONENT.value: partial}
+
+
+def get_headers(inertia_headers: InertiaHeaderType) -> dict[str, Any]:
+    """Return headers for Inertia responses."""
+    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,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__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: str | None = None
+    """Optionally supply a path where unauthorized requests should redirect."""
+    extra_page_props: dict[str, Any] = field(default_factory=dict)
+    """A dictionary of values to automatically add in to page props on every request."""

litestar_vite/inertia/exception_handler.py

@@ -0,0 +1,91 @@
+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,
+    InternalServerException,
+    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 (
+    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_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_500_INTERNAL_SERVER_ERROR,
+)
+
+from litestar_vite.inertia.response import InertiaBack, InertiaRedirect, InertiaResponse, error
+
+if TYPE_CHECKING:
+    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 = HTTP_409_CONFLICT
+
+
+def exception_to_http_response(request: Request[UserT, AuthT, StateT], exc: Exception) -> Response[Any]:
+    """Handler for all exceptions subclassed from HTTPException."""
+    inertia_enabled = getattr(request, "inertia_enabled", False) or getattr(request, "is_inertia", False)
+    if isinstance(exc, NotFoundError):
+        http_exc = NotFoundException
+    elif isinstance(exc, RepositoryError):
+        http_exc = _HTTPConflictException  # type: ignore[assignment]
+    else:
+        http_exc = InternalServerException  # type: ignore[assignment]
+    if not inertia_enabled:
+        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__))))
+    is_inertia = getattr(request, "is_inertia", False)
+    status_code = getattr(exc, "status_code", HTTP_500_INTERNAL_SERVER_ERROR)
+    preferred_type = MediaType.HTML if inertia_enabled and not is_inertia else MediaType.JSON
+    detail = getattr(exc, "detail", "")  # litestar exceptions
+    extras = getattr(exc, "extra", "")  # msgspec exceptions
+    content = {"status_code": status_code, "message": getattr(exc, "detail", "")}
+    inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
+    if extras:
+        content.update({"extra": extras})
+    flash(request, detail, category="error")
+    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,reportUnknownArgumentType]
+        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)
+    if status_code in {HTTP_422_UNPROCESSABLE_ENTITY, HTTP_400_BAD_REQUEST}:
+        return InertiaBack(request)
+    if (
+        status_code == HTTP_401_UNAUTHORIZED
+        and inertia_plugin.config.redirect_unauthorized_to is not None
+        and not request.url.path.startswith(inertia_plugin.config.redirect_unauthorized_to)
+    ):
+        return InertiaRedirect(
+            request,
+            redirect_to=inertia_plugin.config.redirect_unauthorized_to,
+        )
+    return InertiaResponse[Any](
+        media_type=preferred_type,
+        content=content,
+        status_code=status_code,
+    )

litestar_vite/inertia/middleware.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+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
+
+
+async def redirect_on_asset_version_mismatch(request: Request[UserT, AuthT, StateT]) -> InertiaRedirect | None:
+    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)
+    template_engine = vite_plugin.template_config.to_engine()
+    if inertia_version == template_engine.asset_loader.version_id:
+        return None
+    return InertiaRedirect(request, redirect_to=str(request.url))
+
+
+if TYPE_CHECKING:
+    from litestar.types import Receive, Scope, Send
+
+
+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 = await 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,64 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from litestar.exceptions import ImproperlyConfiguredException
+from litestar.middleware import DefineMiddleware
+from litestar.middleware.session import SessionMiddleware
+from litestar.plugins import InitPluginProtocol
+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.middleware import InertiaMiddleware
+from litestar_vite.inertia.request import InertiaRequest
+from litestar_vite.inertia.response import InertiaResponse
+from litestar_vite.inertia.routes import generate_js_routes
+
+if TYPE_CHECKING:
+    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."""
+    js_routes = generate_js_routes(app)
+    app.state.js_routes = js_routes
+
+
+class InertiaPlugin(InitPluginProtocol):
+    """Inertia plugin."""
+
+    __slots__ = ("config",)
+
+    def __init__(self, config: InertiaConfig) -> None:
+        """Initialize ``Inertia``.
+
+        Args:
+            config: configure and start Vite.
+        """
+        self.config = config
+
+    def on_app_init(self, app_config: AppConfig) -> AppConfig:
+        """Configure application for use with Vite.
+
+        Args:
+            app_config: The :class:`AppConfig <.config.app.AppConfig>` instance.
+        """
+        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)
+        return app_config