Litestar

Start here: Frameworks
Common recipes: micro.install(app) opens the app on startup and binds the active app inside route handlers, so patterns resolve their backends ambiently without explicit backend= wiring. Call it after Litestar(...), which builds the middleware stack at construction.

grelmicro.integrations.litestar

Litestar integration that opens a Grelmicro app and binds it per request.

install

install(
    app: Litestar, micro: Grelmicro, *, ambient: bool = True
) -> None

Wire micro into a Litestar app.

Opens async with micro: on startup and closes it after shutdown, so the components are registered before the first request. Startup hooks and lifespan managers already passed to Litestar(...) keep running.

When ambient is True, wraps the app's ASGI handler so patterns resolve through Grelmicro.current() inside route handlers. The wrap sits outside every middleware Litestar built, so one that resolves a backend ambiently always runs inside the request scope.

Call it after the app is built, since Litestar builds its middleware stack at construction time:

from litestar import Litestar

from grelmicro import Grelmicro

micro = Grelmicro(uses=[...])
app = Litestar(route_handlers=[...])
micro.install(app)

Prefer the polymorphic micro.install(app), which detects the framework and calls this for you.

PARAMETER	DESCRIPTION
`app`	The Litestar application to wire. TYPE: `Litestar`
`micro`	The `Grelmicro` app to open in the lifespan and bind per request. TYPE: `Grelmicro`
`ambient`	Wrap the app's ASGI handler with `GrelmicroMiddleware` so patterns resolve ambiently inside route handlers. Default `True`. Pass `False` to skip it. TYPE: `bool` DEFAULT: `True`

install_error_responses

install_error_responses(
    app: Litestar, errors: ErrorResponses
) -> None

Render grelmicro rejections in a standard format on a Litestar app.

Registers one exception handler per rejection grelmicro raises to turn a caller away, so a rate limiter, a bulkhead, an open circuit breaker, an elapsed deadline, or an idempotency conflict answers the client with an application/problem+json body instead of a 500.

Litestar looks a handler up through the raised exception's class hierarchy, so registering AdmissionError covers every rejection under it, including one a later release adds.

Call it after the app is built and before it serves, since Litestar resolves each route's handlers on its first request. micro.install(app) calls this when ErrorResponses() is registered, so a direct call is only for an app that never goes through install.

from grelmicro.http import ErrorResponses
from grelmicro.integrations.litestar import install_error_responses

install_error_responses(app, ErrorResponses())

install_middleware

install_middleware(
    app: Litestar, components: Sequence[Any]
) -> None

Add the ASGI middleware each registered component asks for.

A component that carries asgi_middleware() returns the middleware class and the arguments to build it with, and this wraps the app's ASGI handler with it. Registration order is wrapping order, so the first one registered is the outermost and answers first.

Each one is wrapped inside the binding, so a middleware that resolves a backend ambiently finds the app bound.

Call it after the app is built, since Litestar builds its middleware stack at construction time. micro.install(app) calls this with the components it found, so a direct call is only for an app that never goes through install.

PARAMETER	DESCRIPTION
`app`	The Litestar application to wire. TYPE: `Litestar`
`components`	The registered components that carry an ASGI middleware. TYPE: `Sequence[Any]`

is_bound

is_bound(app: Litestar) -> bool

Return whether the per-request binding middleware is in place.

Called by Grelmicro.check_ambient_binding and Grelmicro.describe to catch an app that never had micro.install(app) called on it. True for both the wrap install adds and a DefineMiddleware(GrelmicroMiddleware) passed to Litestar(middleware=[...]).

PARAMETER	DESCRIPTION
`app`	The Litestar application to inspect. TYPE: `Litestar`

error_response

error_response(
    request: Request,
    *,
    status: int,
    detail: str | None = None,
    extensions: dict[str, Any] | None = None,
) -> Response

Answer from your own exception handler in the app's error format.

The Litestar counterpart of the Starlette helper. The format is read from the app, so a service that registered ErrorResponses.tmf() answers in TMF from here too.

from grelmicro.integrations.litestar import error_response


def handle(request: Request, exc: InsufficientFunds) -> Response:
    return error_response(
        request, status=409, detail="Not enough to cover this charge."
    )

PARAMETER	DESCRIPTION
`request`	The request being answered, which knows its app. TYPE: `Request`
`status`	HTTP status code of the response. TYPE: `int`
`detail`	Explanation of this occurrence, safe to show a client. TYPE: `str \| None` DEFAULT: `None`
`extensions`	Extra members to carry, where the format has room for them. TYPE: `dict[str, Any] \| None` DEFAULT: `None`

PARAMETER	DESCRIPTION
`app`	The Litestar application to wire. TYPE: `Litestar`
`errors`	The registered component that renders each rejection. TYPE: `ErrorResponses`