quadkit-web

Web layer for Quadkit Framework — ASGI, routing, middleware, and API tooling.

Overview

quadkit-web provides an ASP.NET Core-inspired HTTP layer built on Starlette with constructor injection, a Result-to-HTTP bridge that maps domain errors to status codes automatically, first-class middleware, guard, and filter pipelines, and OpenAPI docs auto-generation.

Full documentation: docs.quadkit.dev

Install

uv add quadkit quadkit-web[granian]

# With optional server backends
uv add "quadkit-web[uvicorn]"   # uvicorn
uv add "quadkit-web[hypercorn]"  # hypercorn
uv add "quadkit-web[security]"   # itsdangerous for signing
uv add "quadkit-web[templates]"  # Jinja2 template support
uv add "quadkit-web[websocket]"  # WebSocket support

Quick Start

from quadkit import Application
from quadkit.di.module import Module, module
from quadkit.web import Controller, WebModule, WebProvider, get


class HelloController(Controller):
    @get("/hello")
    async def hello(self) -> dict[str, str]:
        return {"message": "Hello from Quadkit"}


@module(
    imports=[
        WebModule.configure(
            controllers=[HelloController],
            host="127.0.0.1",
            port=8000,
        )
    ]
)
class AppModule(Module):
    pass


async def main() -> None:
    async with Application.boot(modules=[AppModule]) as app:
        web = await app.container.resolve(WebProvider)
        web.run_server(host="127.0.0.1", port=8000)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

Configuration

Zero-config usage: Call WebModule.configure() with no arguments to use all defaults.

Option 1 — YAML file

# application.yaml
web:
  server:
    host: "0.0.0.0"
    port: 8000
    workers: 4
  cors:
    allowed_origins:
      - "https://app.example.com"
  rate_limit:
    enabled: true
    default_limit: "100/minute"

Option 2 — Profiles + Environment Variables (recommended)

export QK_WEB__SERVER__HOST=0.0.0.0
export QK_WEB__SERVER__PORT=8080
export QK_WEB__SECURITY__CORS__ALLOWED_ORIGINS='["https://app.example.com"]'

Option 3 — Python

from quadkit.web import WebModule
from quadkit.web.config import WebConfig, ServerConfig, RateLimitConfig

WebModule.configure(
    controllers=[UserController, OrderController],
    web_config=WebConfig(
        server=ServerConfig(host="0.0.0.0", port=8080, workers=4),
        rate_limit=RateLimitConfig(
            enabled=True,
            default_limit=200,
            default_window=60,
        ),
    ),
)

Config reference

Module Factory Methods

Key Features

• Controller pattern — subclass Controller and annotate methods with HTTP decorators
• Result-to-HTTP bridge — Result[T, DomainError] maps automatically to status codes (404, 422, 403, etc.)
• HTTP decorators — @get, @post, @put, @delete, @patch, @websocket, etc.
• Auto-discovery — WebModule.configure(discover=["my_app.api.v1"])
• Middleware pipeline — register ASGI middleware via MiddlewareRegistry
• Exception filters — DefaultExceptionFilter handles DomainError and HTTPError globally
• Static files, API docs, debug routes — configurable via WebConfig
• Rate limiting — per-path rules with memory or Redis storage backend
• Security — CORS wildcard blocked in production, CSRF enabled by default

Testing

from quadkit import Application
from quadkit.web import WebModule


async def test_controller():
    async with Application.boot(modules=[WebModule.stub()]) as app:
        web = await app.container.resolve(WebProvider)
        assert web.starlette is not None

Key Source Files