/litestar-granian

name: litestar-granian
description: "Use when working with 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` replaces Litestar's `run` command with a supervised Granian command and bridges Litestar's active log formatter into Granian worker processes. It requires Granian 2.8.0 or later (using Granian 2.8.8).

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. When `litestar run` starts, `litestar-granian` inspects the active `"litestar"` standard-library logger (or `app.logging_config`, including `standard_lib_logging_config` wrapped by `StructlogPlugin`), serializes the active formatter into a temporary JSON `dictConfig` (`--log-config`), and reconstructs matching `generic` (`_granian`) and `access` (`granian.access`) formatters inside Granian worker processes.

Defaults in 0.17.0 / Granian 2.8.8

| 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 (`512` in Granian when unset) | | Blocking threads | `1` on ASGI (fixed; `> 1` only supported on WSGI; `30s` idle timeout) | | Runtime mode | `auto` (resolves to `mt` on ASGI) | | Event loop | `auto` (Granian's standard selection; optional loops require their extras) | | Async task implementation | `asyncio` (optional experimental `rust` on Python < 3.12) | | 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` (`--wc`, `--web-concurrency`, `-W`), `--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-no-log`, `--granian-log-level`, `--granian-access-log` / `--granian-no-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` / `--no-ssl-client-verify`, `--create-self-signed-cert` | | Worker lifecycle | `--respawn-failed-workers` / `--no-respawn-failed-workers`, `--respawn-interval`, `--workers-lifetime`, `--workers-kill-timeout`, `--workers-max-rss`, `--rss-sample-interval`, `--rss-samples` | | Reload & debug (dev) | `--reload` (`-r`), `--reload-paths` (`--reload-dir`, `-R`), `--reload-include` (`-I`), `--reload-exclude` (`-E`), `--reload-ignore-dirs`, `--reload-ignore-patterns`, `--reload-ignore-paths`, `--reload-tick`, `--reload-ignore-worker-failure`, `--debug` (`-d`), `--pdb` (`--use-pdb`, `-P`) | | Operations | `--uds` (`--unix-domain-socket`, `-U`), `--uds-permissions`, `--fd` (`--file-descriptor`, `-F`), `--url-path-prefix`, `--process-name`, `--pid-file`, `--working-dir`, `--env-files`, `--metrics` / `--no-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 o