Add Litestar adapter

[fsecada01]

Overview

Add a first-class Litestar adapter to component-framework, giving Litestar users the same ergonomics as the existing FastAPI and Django adapters.

Background

FastAPI and Django adapters ship today. Flask (#5) and Litestar (this issue) were identified as gap in #4 during the 0.3.0 dependency refactor.

Required Components

1. Optional Extras Group

Add a [litestar] optional extras group in pyproject.toml:

[project.optional-dependencies]
litestar = ["litestar>=2.0"]

2. Adapter Module (adapters/litestar.py)

• LitestarRenderer subclass of Renderer using Litestar's template engine
• HTTP endpoint handler (mirrors adapters/fastapi.py structure)
• ImportError guard at module top using _require_extra("litestar", "litestar")

3. Optional WebSocket Handler (adapters/litestar_websocket.py)

• Async WebSocket consumer following the FastAPI WebSocket adapter pattern
• ImportError guard advertising [litestar] extra

4. Test File (tests/test_litestar_adapter.py)

• pytest.importorskip("litestar", ...) skip guard
• Adapter-level tests mirroring test_fastapi_adapter.py

5. Documentation

• Add Litestar to the Adapter Support table in README.md
• Add install instructions: pip install "component-framework[litestar]"
• Add example in examples/litestar_example.py

Constitution Adapter Contract

Per the project constitution (Adapter Contract principle), this adapter must:

• Live entirely in adapters/ — zero changes to core/
• Ship with its own optional extras group
• Have ImportError guards with actionable messages
• Be covered by its own CI isolation matrix row

Reference

• Issue Make FastAPI/JinjaX optional dependencies; add Flask and Litestar adapter stubs #4: dependency refactor that identified this gap
• Issue Add Flask adapter #5: Flask adapter (parallel work)
• Adapter pattern: see src/component_framework/adapters/fastapi.py

[fsecada01]

Litestar Adapter — Detailed Implementation Spec

I'm building this adapter for Atelier CMS, a multi-tenant CMS on Litestar 2.x + JinjaX. Here's a detailed spec of what the adapter needs to do, covering where Litestar diverges from FastAPI and what Atelier specifically requires.

---

Key Litestar Differences from FastAPI

1. Route Handlers vs. APIRouter

FastAPI uses APIRouter + app.include_router(...). Litestar uses decorated handler functions or Controller classes registered directly:

# FastAPI (existing adapter pattern)
router = APIRouter()

@router.post("/components/{name}")
async def handle_component(name: str, request: Request): ...

app.include_router(router)

# Litestar equivalent
from litestar import post, Router

@post("/components/{name:str}", name="component_handle")
async def handle_component(name: str, request: Request, ...) -> Response: ...

# Registered at app level:
Litestar(route_handlers=[handle_component, ...])
# OR via a Router:
component_router = Router(path="", route_handlers=[handle_component])

The adapter should expose a create_component_router() function that returns a litestar.Router (or a list of handlers), so the app author registers it themselves — matching how Litestar apps are structured.

2. Dependency Injection

Litestar's DI is declared in dependencies={} dicts (on the app, router, or handler), not via Depends(). However, for a self-contained adapter, using request.app.state to store the registry is cleaner:

# Store registry on app startup
app = Litestar(
    on_startup=[lambda app: setattr(app.state, "component_registry", registry)],
    route_handlers=[...],
)

# Read it in the handler
@post("/components/{name:str}")
async def handle_component(name: str, request: Request) -> Response:
    registry = request.app.state.component_registry
    component_cls = registry.get(name)
    ...

3. Request Body Parsing

Litestar doesn't auto-parse JSON bodies the same way. Use await request.json() (returns dict) or declare a data parameter with a Pydantic/msgspec model:

from litestar import post
from litestar.connection import Request

@post("/components/{name:str}")
async def handle_component(name: str, request: Request) -> Response:
    body: dict = await request.json()
    event = body.get("event")
    payload = body.get("payload", {})
    state = body.get("state", {})
    ...

4. Response Types

Use litestar.response.Response with explicit media_type:

from litestar.response import Response
from litestar.status_codes import HTTP_200_OK

return Response(
    content={"html": rendered_html, "state": serialized_state, "component_id": cid},
    media_type="application/json",
    status_code=HTTP_200_OK,
)

For HTMX-first use cases (returning HTML directly for hx-swap), use:

from litestar.response import Response

return Response(content=rendered_html, media_type="text/html")

5. WebSocket

Litestar WebSocket handlers use the @websocket decorator, not WebSocket as a function argument:

from litestar import websocket
from litestar.connection import WebSocket

@websocket("/components/ws/{name:str}")
async def component_ws(socket: WebSocket, name: str) -> None:
    await socket.accept()
    try:
        while True:
            data = await socket.receive_json()
            # ... handle event ...
            await socket.send_json({"html": ..., "state": ...})
    except Exception:
        await socket.close()

6. CSRF Considerations

Litestar has built-in CSRF protection (CSRFConfig). Component POST endpoints need to either:

• Include the CSRF token in the state payload and validate it, OR
• Be excluded from CSRF checks via opt={"exclude_from_csrf": True} on the handler

For HTMX-driven components, the client should send the CSRF token as a request header (X-CSRFToken) which Litestar validates automatically if CSRFConfig.header_name is configured.

7. Middleware

Litestar middleware follows the ASGIMiddleware protocol (preferred in 2.15+; AbstractMiddleware is deprecated):

# If the adapter needs session or other middleware
from litestar.middleware import ASGIMiddleware  # Litestar >= 2.15

---

JinjaX Renderer for Litestar

Atelier's stack: Litestar + JinjaX (JinjaX catalog registered via engine_callback in TemplateConfig). The renderer needs to access the live Jinja2 engine, which is available after app startup via request.app.template_engine.engine:

class LitestarJinjaxRenderer(Renderer):
    """Renderer that delegates to Litestar's JinjaX-extended Jinja2 engine."""

    def __init__(self, request: Request) -> None:
        # Litestar exposes the template engine here after startup
        self._engine = request.app.template_engine.engine  # raw jinja2.Environment

    def render(self, template_name: str, context: dict) -> str:
        # The JinjaX catalog is registered as a Jinja2 extension
        # and also stored on app.state by configure_jinja_engine()
        catalog = getattr(self._engine, "_jinjax_catalog", None)
        if catalog is not None:
            return catalog.render(template_name, **context)
        # Fallback: plain Jinja2 template
        return self._engine.get_template(template_name).render(**context)

A plain LitestarRenderer (no JinjaX) would use request.app.template_engine.get_template() directly.

---

Recommended Adapter API Surface

# adapters/litestar.py

from component_framework.adapters.litestar import (
    LitestarRenderer,           # Renderer subclass for plain Litestar/Jinja2 templates
    LitestarJinjaxRenderer,     # Renderer subclass for JinjaX catalogs
    create_component_router,    # Returns litestar.Router with POST + optional WS handlers
)

# In the app's entry point (e.g. app.py):
from component_framework.adapters.litestar import create_component_router

component_router = create_component_router(
    renderer_class=LitestarJinjaxRenderer,
    path_prefix="/components",          # default
    include_websocket=True,             # optional
)

app = Litestar(
    route_handlers=[..., component_router],
)

---

Atelier-Specific Use Cases

These are the admin panel interactions that currently require bespoke Litestar route handlers. component-framework would consolidate them into typed Component classes with explicit state:

Current pattern	With component-framework
POST /admin/pages/{id}/blocks/add	BlockBuilderComponent.on_add_block()
PATCH /admin/pages/{id}/blocks/{block_id}	BlockEditorComponent.on_update_content()
POST /admin/forms/new/fields/add	FormBuilderComponent.on_add_field()
DELETE /admin/media/{id} + HTMX swap	MediaGridComponent.on_delete()
GET /admin/media?q=... (media picker search)	MediaPickerComponent.on_search()

Each is currently a one-off route handler. Consolidating into Component classes makes state management explicit, testable via ComponentTestCase, and reusable across tenants.

---

Testing Pattern

Litestar's async test client is AsyncTestClient from litestar.testing:

# tests/test_litestar_adapter.py
import pytest
litestar = pytest.importorskip("litestar", reason="requires component-framework[litestar]")

from litestar import Litestar
from litestar.testing import AsyncTestClient
from component_framework.adapters.litestar import create_component_router
from component_framework.core import Component, registry

@registry.register("ping")
class PingComponent(Component):
    template_name = "ping"

    def mount(self):
        self.state["value"] = "pong"

    def get_context(self):
        return {"value": self.state["value"]}

@pytest.fixture
async def client():
    app = Litestar(route_handlers=[create_component_router()])
    async with AsyncTestClient(app=app) as c:
        yield c

async def test_component_mount(client):
    resp = await client.post(
        "/components/ping",
        json={"event": "mount", "payload": {}, "state": ""},
    )
    assert resp.status_code == 200
    assert "pong" in resp.json()["html"]

Note: AsyncTestClient requires pytest-anyio or anyio as a test dependency. Litestar tests use asyncio_mode = "auto" in pytest.ini / pyproject.toml.

---

pyproject.toml Addition

[project.optional-dependencies]
litestar = ["litestar>=2.15"]   # 2.15 for ASGIMiddleware; 2.0+ for core patterns

---

CI Matrix Row

# .github/workflows/test.yml
- name: "Litestar adapter"
  run: |
    pip install ".[litestar]"
    pytest tests/test_litestar_adapter.py -v

---

Happy to open a draft PR for the adapter once I've validated the patterns against Atelier in production. Can contribute LitestarRenderer, LitestarJinjaxRenderer, create_component_router, the WebSocket handler, and examples/litestar_example.py as a starting point.