/litestar-granian

name: litestar-granian
description: "Auto-activate for litestar_granian, GranianPlugin, litestar run Granian options, runtime threads, HTTP/2, TLS, access logs, metrics, static mounts, or worker lifecycle. Not for non-Granian servers."

litestar-granian

`litestar-granian` 0.16.0 replaces Litestar's `run` command with a Granian-backed command and integrates Granian loggers with Litestar logging. It requires Granian 2.7.9 or later (the current lock uses 2.8.1).

Code Style Rules

• Keep handlers async when they perform I/O.
• Configure the server at the command line or programmatically via `granian.Granian`.
• `GranianPlugin` takes only an optional `static` mode keyword argument (`"off"` or `"auto"`).
• Use the `litestar run` option names documented here. Do not substitute similarly named options from older Granian or Uvicorn releases.

Quick Reference

Register the plugin

from litestar import Litestar, get
from litestar_granian import GranianPlugin


@get("/health")
async def health() -> dict[str, str]:
    """Return health check response."""
    return {"status": "ok"}


app = Litestar(
    route_handlers=[health],
    plugins=[GranianPlugin()],
)

litestar --app app:app run

`GranianPlugin` registers the Granian-backed `run` command. During app initialization, it adds missing `_granian` and `granian.access` logger entries and a compatible formatter without replacing user-defined entries. It also handles the standard-library logging configuration wrapped by Litestar's `StructlogPlugin`.

Defaults in 0.16.0 / Granian 2.8.1

| Concern | Default | | --- | --- | | Sockets and Bind | `127.0.0.1:8000` | | HTTP mode | `auto` (HTTP/1 and HTTP/2 supported; HTTP/3 not supported) | | Workers | `1` worker (process on GIL builds; thread on free-threaded builds) | | Runtime threads | `1` per worker | | Runtime blocking threads | Automatically selected | | Blocking threads | Automatically selected (`30s` idle timeout) | | Runtime mode | `auto` (selects single- or multi-threaded Rust runtime) | | Event loop | `auto` (Granian's standard selection; optional loops require their extras) | | Async task implementation | `asyncio` (optional `rust` task scheduling) | | Backlog | `1024` globally (minimum `128`) | | Backpressure | `backlog / workers` per worker (minimum `1`) | | Granian log | Enabled at `info` (`--granian-log`, `--granian-log-level`) | | Access log | Disabled (`--granian-access-log`, `--granian-access-log-fmt`) | | WebSockets | Enabled (`--ws`); automatically disabled in HTTP/2-only mode | | Process supervision | Supervised process group (always) | | Reload | Disabled (`--reload`; not supported on free-threaded Python) | | Metrics | Disabled; `127.0.0.1:9090` when enabled with `--metrics` | | Static-file cache | `86400` seconds; no implicit route or mount | | Minimum TLS protocol | TLS 1.3 (`--ssl-protocol-min [tls1.2\|tls1.3]`) |

Valid Production Controls

litestar --app app:app run \
    --host 0.0.0.0 \
    --port 8000 \
    --workers 4 \
    --runtime-mode auto \
    --runtime-threads 1 \
    --backpressure 1024 \
    --granian-access-log \
    --respawn-failed-workers \
    --workers-lifetime 4h \
    --workers-max-rss 512 \
    --metrics \
    --metrics-address 127.0.0.1 \
    --metrics-port 9090

Use these option families:

| Concern | Options | | --- | --- | | Processes and runtime | `--workers`, `--blocking-threads`, `--blocking-threads-idle-timeout`, `--runtime-threads`, `--runtime-blocking-threads`, `--runtime-mode`, `--loop`, `--task-impl` | | Capacity and flow control | `--backlog`, `--backpressure` | | Protocols | `--http [auto\|1\|2]`, `--ws` / `--no-ws`, `--http1-*`, `--http2-*` | | Granian logging | `--granian-log`, `--granian-log-level`, `--granian-access-log`, `--granian-access-log-fmt` | | Litestar logging | `--log-config` (formatter matching is automatic) | | TLS & mTLS | `--ssl-certificate` (`--ssl-certfile` alias), `--ssl-keyfile`, `--ssl-keyfile-password`, `--ssl-protocol-min`, `--ssl-ca`, `--ssl-crl`, `--ssl-client-verify` | | Worker lifecycle | `--respawn-failed-workers`, `--respawn-interval`, `--workers-lifetime`, `--workers-kill-timeout`, `--workers-max-rss`, `--rss-sample-interval`, `--rss-samples` | | Reload (dev) | `--reload`, `--reload-paths` (`--reload-include` alias), `--reload-ignore-dirs` (`--reload-exclude` alias), `--reload-ignore-patterns`, `--reload-ignore-paths`, `--reload-tick`, `--reload-ignore-worker-failure` | | Operations | `--uds`, `--uds-permissions`, `--fd`, `--process-name`, `--pid-file`, `--working-dir`, `--env-files`, `--metrics`, `--metrics-address`, `--metrics-port`, `--metrics-scrape-interval` | | Static mounts | Repeatable `--static-path-route` and `--static-path-mount`, plus `--static-path-dir-to-file` and `--static-path-expires` |

Supervision and Litestar CLI Parity

`litestar run` has one execution model: the Litestar parent enters server lifespans once and supervises a fresh Granian child process group.

• **POSIX:** Starts Granian in a new session (`start_new_session=True`) and forwards signals (`SIGINT`, `SIGTERM`, `SIGHUP`) to the process group (`os.killpg`).
• **Windows:** Uses a new process group (`CREATE_NEW_PROCESS_GROUP`) and `CTRL_BREAK_EVENT` for graceful shutdown, escalating to list-based `taskkill` only if needed.
• **Graceful Shutdown & Deadlines:** The first termination signal is forwarded once and starts a deadline of `--workers-kill-timeout` plus five seconds (the CLI default is 5 seconds). A second signal or an expired deadline kills the process group.
• **Server Lifespans:** Litestar's server lifespans stay active until Granian exits and are unwound cleanly after child termination.
• **Sidecar Variables:** Server-lifespan sidecars receive the resolved `LITESTAR_APP`, `LITESTAR_HOST`, and `LITESTAR_PORT`, which is how frontend dev-server sidecars (e.g. Vite) learn the real server bind.
• **Socket Activation:** Inherited file descriptors (`-F` / `--