Korvex

A fast router for Python, written in Rust, with an optional ASGI app on top.

pip install korvex

The router

Router maps a path and an HTTP method to a handler name. It never calls your code: what you do with the name is up to you.

from korvex import Router

router = Router()
router.get("/users/{id:int}", "get_user")
router.post("/users", "create_user", middleware=["auth"])

router.match("/users/42")         # ("get_user", {"id": "42"}, ())
router.match("/users", "POST")    # ("create_user", {}, ("auth",))
router.match("/nope")             # None
router.match("/users", "DELETE")  # raises MethodNotAllowed, .allowed == ["POST"]

Path syntax

Captured values are always strings. When several routes could match, the most specific one wins: literal, then {id:int}/{id:uuid}, then {id}, then *path.

API

Invalid paths or methods raise ValueError.

match keeps the last 1,024 distinct lookups in a cache, and adding or removing a route clears it. Its results are shared between calls, so they are immutable: params is a read-only mapping and middleware a tuple.

Route groups

api = router.group("/api", middleware=["auth"])
api.get("/users", "list_users")             # GET /api/users, middleware ["auth"]

admin = api.group("/admin", middleware=["admin"])
admin.get("/stats", "stats")                # GET /api/admin/stats, middleware ["auth", "admin"]

The ASGI app

App runs the matched handler for you. Serve it with any ASGI server (uvicorn, hypercorn, granian...).

from korvex import App, Response

app = App()

@app.get("/users/{id:int}", middleware=["auth"])
async def get_user(request, id):
    return Response.json({"id": id})

@app.middleware("auth")
def auth(request):
    if request.headers.get("Authorization") is None:
        return Response.text("Unauthorized", status=401)  # stops here
    return None                                          # carries on

pip install "korvex[serve]"   # installs uvicorn
uvicorn mymodule:app

• Handlers receive the Request plus path params as keyword arguments, and return a Response. Middleware returns a Response to answer early, or None to continue. Both can be sync or async.
• Request has method, path, headers, query_params, path_params, and await request.body() / await request.json().
• Response(body, status=, headers=), Response.text(...), Response.json(...), Response.redirect(...).
• Unknown paths get a 404; known paths with the wrong method get a 405 with an Allow header.
• Routes registered on app.router directly (for example through a group) are linked to a function with @app.handler("name").

More in examples/.

Performance

Under load

The same small app (1,000 routes, one JSON endpoint) in each framework, served the same way (uvicorn, one worker, one CPU core) and flooded with requests to random URLs by oha:

• Every framework uses a full CPU core under load, so requests per second is also how much work each one gets out of that core.
• Starlette, FastAPI and Django try routes one by one: the ranges go from the tested route declared after the 1,000 others to declared first. Starlette's best case comes close to Korvex.
• No request failed. Throughput holds steady as clients are added; latency grows because requests queue, not because each one gets slower. After the flood, memory stays flat and speed is back to normal.

Reproduce with uv run python benches/load_test.py (needs cargo install oha, takes about 9 minutes).

Router alone

Route matching only, without any server:

Median time per lookup, 10,000 routes:

• Korvex is the fastest in both cases, and its time stays flat as routes are added. Django and Starlette try routes one by one, so they slow down linearly.
• Korvex, Litestar and Sanic cache the last 1,024 lookups. The cache helps most with static URLs; URLs with parameters (/users/1, /users/2, ...) are often different, so they hit it less.
• With few routes, the server and the handler cost more than the router. With many routes, a router that tries them one by one becomes the main cost (see Under load).

Reproduce with uv run pytest benches/bench_router.py --benchmark-only --benchmark-json=benches/results.json, then uv run python benches/plot.py to redraw both charts. Results depend on the machine: measure your own workload before relying on any number.

Development

uv run maturin develop --release   # build the Rust extension
uv run pytest                      # Python tests
cargo test                         # Rust tests

See CONTRIBUTING.md.

License

MIT