Korvex

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

Korvex is young (alpha). Its routing is fast (see Performance), but it lacks some of what full frameworks offer: WebSockets, validation, OpenAPI. The roadmap lists what's coming.

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

{id:int} gives an int and {id:uuid} a uuid.UUID; every other captured value is a string. 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, cookies, and await request.body(), await request.json(), await request.form(). A form maps each field to its values; files from a multipart form are UploadedFiles (filename, content_type, data). A body that can't be parsed is answered with a 400.
• Response(body, status=, headers=), Response.text(...), Response.json(...), Response.redirect(...), and response.set_cookie(...) / response.delete_cookie(...).
• Response.stream(chunks) sends a body piece by piece, from a sync or async generator. Response.file(path, filename=None) sends a file in chunks (with filename, as a download). app.static("/static", "public") serves a directory; paths that leave it get a 404.
• HEAD requests are answered by the GET route, without the body.
• Unknown paths get a 404; known paths with the wrong method get a 405 with an Allow header.
• raise HTTPException(404, "user not found") in a handler or middleware answers with that error. @app.exception_handler(404) (a status) or @app.exception_handler(ValueError) (an exception class) customizes the response. Any other exception gives a 500 and is logged to the korvex logger.
• app.group(prefix, middleware=[...]) works like router.group(), with decorators: api = app.group("/api"), then @api.get("/users"). Groups nest.
• Routes registered on app.router directly are linked to a function with @app.handler("name").
• @app.on_startup and @app.on_shutdown run a function (sync or async) when the server starts and stops, for example to open and close a database pool. Shutdown hooks run in reverse order. If a startup hook raises, the server doesn't start. Both @app.on_startup and @app.on_startup() work.

More in examples/. To put it in production (behind nginx or Caddy, in Docker, on AWS Lambda or Vercel), see the deployment guide.

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.
• Falcon, and Starlette in its best case, come within about 10% of Korvex.
• 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. BlackSheep tries them one by one too, but sorts them itself, deepest first, so here the tested route always comes last.
• 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.

Robyn isn't included: it runs its own server, so it wouldn't be the same comparison. Korvex plans its own built-in server (see the roadmap), and the two will be compared then.

Reproduce with uv run python benches/load_test.py (needs cargo install oha, takes about 11 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, and ROADMAP.md for what's planned.

License

MIT