git:20260723.07bc8a4 to git:20260807.656b60a

---

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 Granian worker lifecycle. Not for another ASGI server's native CLI — use that server's documentation."

---

# litestar-granian

command and integrates Granian loggers with Litestar logging. It requires

Granian 2.7 or later.

## Code Style Rules

- Keep handlers async when they perform I/O.

- 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

```python

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()],

)

```

```bash

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`.

| Concern | Default |

| --- | --- |

| Bind | `127.0.0.1:8000` |

| HTTP mode | `auto` |

| Workers | `1` |

| Runtime threads | `1` per worker |

| Runtime mode | `auto` |

| Event loop | `auto` |

| Async task implementation | `asyncio` |

| Backlog | `1024` globally |

| Backpressure | `backlog / workers` per worker |

| Granian log | Enabled at `info` |

| Access log | Disabled |

| WebSockets | Enabled except in HTTP/2-only mode |

| Reload | Disabled |

| Static-file cache | `86400` seconds; no implicit route or mount |

| Minimum TLS protocol | TLS 1.3 |

`--runtime-mode st` only when preserving the earlier single-thread runtime is

intentional.

### Valid production controls

```bash

litestar --app app:app run \

--host 0.0.0.0 \

--workers 4 \

--runtime-mode auto \

--runtime-threads 1 \

--backpressure 1024 \

--granian-access-log

```

Use these option families:

| Concern | Options |

| --- | --- |

| Processes and runtime | `--workers`, `--blocking-threads`, `--runtime-threads`, `--runtime-blocking-threads`, `--runtime-mode`, `--loop`, `--task-impl` |

| Capacity | `--backlog`, `--backpressure` |

| Protocols | `--http`, `--ws` / `--no-ws`, `--http1-*`, `--http2-*` |

| Granian logging | `--granian-log`, `--granian-log-level`, `--granian-access-log`, `--granian-access-log-fmt` |

| TLS | `--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 | `--reload`, `--reload-paths` (`--reload-include` alias), `--reload-ignore-dirs` (`--reload-exclude` alias), `--reload-ignore-patterns`, `--reload-ignore-paths`, `--reload-tick` |

| Operations | `--uds`, `--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` |

`--static-path-route` and `--static-path-mount` pair by position. Pass both;

durations such as `1h` and `1d`; pass `0` to disable caching.

<workflow>

## Workflow

### Step 1: Match the project's deployment stack

Use `GranianPlugin` when the project already uses `litestar-granian` or needs

its Granian-specific CLI, HTTP/2, runtime, worker-lifecycle, metrics, or static

mount controls.

Keep the project's existing ASGI server when its deployment platform, process

manager, observability, or operational runbooks depend on that server. Do not

replace an established server solely because Granian is available.

Use the bare `granian` CLI only when deployment tooling intentionally invokes

Granian directly. Its CLI is a separate surface; consult the matching Granian

release instead of copying `litestar run` options.

### Step 2: Install and register

```bash

```

Add `GranianPlugin()` to `Litestar(plugins=[...])`, then run the application

through `litestar --app <module>:<app> run`.

```bash

```

### Step 4: Configure the deployment

Measure the application before changing workers, runtime threads, or

backpressure. Preserve the `auto` runtime defaults unless load tests justify a

specific runtime mode.

Terminate TLS at the platform proxy when that is the project's established

boundary. For Granian-managed TLS, pass both the certificate and key:

```bash

litestar --app app:app run \

--ssl-certificate /etc/ssl/certs/app.crt \

--ssl-keyfile /etc/ssl/private/app.key

```

### Step 5: Verify the effective command

```bash

litestar --app app:app run --help

```

</workflow>

<guardrails>

## Guardrails

`--runtime-threads`, `--runtime-blocking-threads`, and `--runtime-mode`.

`--granian-access-log` and `--granian-access-log-fmt`.

- **Do not treat the plugin CLI as the bare Granian CLI.** The option names

overlap but are not identical.

- **Do not claim that registering the plugin changes every deployment.**

`GranianPlugin` replaces Litestar's `run` command; an external ASGI command

still controls its own server lifecycle.

- **Do not force Granian into an established deployment stack.** Match the

server to the project's platform and operational requirements.

launcher disables WebSockets when `--http http2` is selected.

- **Do not rely on an implicit static route.** Pair every repeatable

`--static-path-route` with a `--static-path-mount`.

- **Do not perform blocking I/O in an async handler.** It blocks the worker's

async runtime.

</guardrails>

<validation>

## Validation Checkpoint

- [ ] The project intentionally selected Granian over its existing ASGI server.

- [ ] `GranianPlugin()` is registered when deployment uses `litestar run`.

- [ ] Every documented option appears in `litestar run --help`.

- [ ] HTTP/2-only mode is not used for required WebSocket endpoints.

- [ ] Static routes and mounts have equal counts and are paired in order.

- [ ] Worker, thread, and capacity changes are backed by load-test results.

- [ ] TLS terminates at the documented platform or Granian boundary.

</validation>

<example>

## Example

**Task:** Run an existing Litestar application with Granian in direct mode,

enable access logs, and expose Granian metrics to a local collector.

```python

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()],

)

```

```bash

litestar --app app:app run \

--host 0.0.0.0 \

--granian-access-log \

--metrics \

--metrics-address 127.0.0.1 \

--metrics-port 9090

```

</example>

## References Index

- [litestar](../litestar/SKILL.md) — application initialization and plugin

registration.

- [litestar-deployment](../litestar-deployment/SKILL.md) — deployment target,

proxy, container, and process-manager selection.

- [litestar-plugins](../litestar-plugins/SKILL.md) — Litestar plugin protocols

and initialization behavior.

## Official References

## Shared Styleguide Baseline

- [General Principles](../litestar-styleguide/references/general.md)

- [Python](../litestar-styleguide/references/python.md)

- [Litestar](../litestar-styleguide/references/litestar.md)