litestar-granian

litestar-granian

litestar-granian is the first-party plugin that integrates the Granian Rust-based ASGI server with Litestar. Adding GranianPlugin() to a Litestar app makes litestar run launch Granian instead of uvicorn — same CLI, much higher throughput, native HTTP/2, and lower memory.

For Litestar apps, always prefer litestar-granian over plain granian CLI: the plugin wires Granian into Litestar's lifespan, signal handling, CLI flags, and dev-mode reload logic.

Code Style Rules

• Use PEP 604 unions: T | None, never Optional[T]
• Consumer Litestar apps that wire GranianPlugin MAY use from __future__ import annotations — canonical Litestar apps do.
• Async all I/O — sync handlers block Granian's async runtime and starve workers.

Quick Reference

Zero-config plugin install

from litestar import Litestar
from litestar_granian import GranianPlugin

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

# Same CLI as before; now backed by Granian
litestar --app app:app run --host 0.0.0.0 --port 8000

# Dev with reload
litestar --app app:app run --reload

Tuned plugin install

GranianPlugin itself takes no configuration — it registers the litestar run CLI command and wires Granian's loggers into Litestar's logging config. All tuning (workers, threads, http, backpressure, SSL, structured access logs) happens on the litestar run command line or via environment variables at deploy time.

from litestar import Litestar
from litestar_granian import GranianPlugin

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

# Production-tuned launch (8 cores, runtime threading mode, HTTP/2, bounded backpressure)
litestar --app app:app run \
    --workers 8 \
    --threads 2 \
    --threading-mode runtime \
    --http auto \
    --backpressure 2000 \
    --log-access \
    --log-access-format json

Production with SSL

litestar --app app:app run \
    --workers 8 \
    --threads 2 \
    --threading-mode runtime \
    --http auto \
    --backpressure 2000 \
    --ssl-certificate /etc/ssl/certs/app.crt \
    --ssl-keyfile /etc/ssl/private/app.key

Granian vs Uvicorn for Litestar

Feature	Granian (litestar-granian)	Uvicorn
Core	Rust (hyper + tokio)	Python
HTTP/2	Native	Requires h2
Throughput	Higher	Moderate
Memory	Lower	Higher
Litestar plugin	First-party (GranianPlugin)	None — generic ASGI
litestar run integration	Yes — drop-in replacement	Default if no plugin
Production default	Preferred	Fallback only

Workflow

Step 1: Install

pip install litestar-granian

Step 2: Register the Plugin

Add GranianPlugin() to the Litestar(plugins=[...]) list. No other code change is required for dev — litestar run now uses Granian.

Step 3: Tune for Deployment

Pass tuning flags to the litestar run command for production. Match --workers to CPU cores, set --threading-mode runtime for async workloads, enable --http auto, set --backpressure to bound queue depth.

Step 4: Add SSL or Reverse Proxy

Either terminate TLS at Granian (--ssl-certificate / --ssl-keyfile) or behind a load balancer. Inside a container without an external proxy, prefer Granian-native SSL.

Step 5: Verify

Run the app, confirm the startup banner mentions Granian, and load-test before going live. Tune workers / backpressure to match peak load without exhausting memory.

Guardrails

• Use litestar-granian for Litestar apps, not the bare granian CLI — the plugin integrates with Litestar lifespan, dev-reload, signal handling, and CLI flags.
• Never mix GranianPlugin with manual granian invocations — the plugin owns the server lifecycle. Pick one.
• Match workers to CPU cores for production. Under-provisioned wastes hardware; over-provisioned bloats memory.
• Use threading_mode="runtime" for async (Litestar) workloads. workers mode is for CPU-bound sync code.
• Set http="auto" unless you have a documented reason to restrict HTTP version. Pure HTTP/2 breaks HTTP/1.1 clients.
• Set backpressure in production — without a bound, traffic spikes lead to unbounded queuing and OOM.
• Use GranianPlugin over uvicorn for all Litestar deployments — higher throughput, native HTTP/2, lower memory.
• Never async def blocked by sync I/O — Granian's event loop must stay free; sync DB/HTTP calls inside async def starve workers.

Validation Checkpoint

Before delivering a Litestar + Granian deployment, verify:

• GranianPlugin is in app.plugins
• No competing manual granian app:app invocations in scripts/Dockerfile
• litestar run --workers matches CPU cores (or has a documented deviation)
• --threading-mode runtime is set on the launch command
• --http auto is set on the launch command
• --backpressure is set for production
• SSL flags or a documented reverse proxy handle TLS for any public service
• No uvicorn in production deps (or a justification is documented)

Example

Task: Production Litestar app with GranianPlugin, tuned for an 8-core host with SSL and structured access logging.

# app.py
from litestar import Litestar, get
from litestar_granian import GranianPlugin


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


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

# Production launch — same CLI, now Granian-backed
litestar --app app:app run --host 0.0.0.0 --port 8443

For Dockerfile / process manager invocations, prefer the same Litestar CLI command rather than calling granian directly.

---

Reference: Granian CLI (when not using the plugin)

If you need to run Granian directly (e.g., for non-Litestar code paths), the standard granian CLI flags are the same ones the Litestar plugin forwards from litestar run:

granian app:main \
  --interface asgi \
  --host 0.0.0.0 \
  --port 8443 \
  --workers 8 \
  --threads 2 \
  --threading-mode runtime \
  --http auto \
  --backpressure 2000 \
  --ssl-certfile /etc/ssl/certs/app.crt \
  --ssl-keyfile /etc/ssl/private/app.key \
  --log-level info \
  --access-log \
  --log-access-fmt json

For Litestar apps, prefer the plugin path described above.

Cross-References

• litestar — Litestar app initialization, plugins, and lifespan.

Official References

• https://github.com/litestar-org/litestar-granian
• https://github.com/emmett-framework/granian
• https://pypi.org/project/granian/

Shared Styleguide Baseline

• Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
• General Principles
• Python
• Litestar
• Keep this skill focused on tool-specific workflows, edge cases, and integration details.