HTTPRouter

Description

HTTPRouter allows registering groups of handlers and plays a key role in routing, directing requests to the appropriate handlers based on HTTP methods, paths, parameters, and other conditions.

HTTPRouter is registered in the same way as any HTTP handler.

from rapidy import Rapidy
from rapidy.http import HTTPRouter, get

@get('/healthcheck')  # /healthcheck
async def healthcheck() -> str:
    return 'ok'

@get('/hello')  # /api/hello
async def hello_handler() -> dict[str, str]:
    return {'hello': 'rapidy'}

api_router = HTTPRouter('/api', [hello_handler])

rapidy = Rapidy(http_route_handlers=[healthcheck, api_router])

HTTPRouter does not support handler registration in the aiohttp style.

None of the aiohttp style handler registration methods will work.

If you need to register an HTTP handler in HTTPRouter, use the methods from the rapidy.http module (get, post, ...).

Nested Routers (HTTPRouter)

HTTPRouter can be nested within each other, allowing for the creation of modular applications.

This is useful, for example, for API versioning.

from rapidy import Rapidy
from rapidy.http import HTTPRouter, get

@get('/hello')  # /api/v1/hello
async def hello_handler_v1() -> dict[str, str | int]:
    return {'hello': 'rapidy', 'version': 1}

@get('/hello')  # /api/v2/hello
async def hello_handler_v2() -> dict[str, str | int]:
    return {'hello': 'rapidy', 'version': 2}

v1_router = HTTPRouter('/v1', [hello_handler_v1])
v2_router = HTTPRouter('/v2', [hello_handler_v2])

api_router = HTTPRouter('/api', [v1_router, v2_router])

rapidy = Rapidy(http_route_handlers=[api_router])

Each HTTPRouter can have its own middleware.

This allows, for example, applying different authentication mechanisms to different route groups.

from rapidy import Rapidy
from rapidy.http import get, HTTPRouter, middleware, Request, StreamResponse
from rapidy.typedefs import CallNext

@get('/hello')  # /api/v1/hello & /api/v2/hello
async def hello_handler() -> dict[str, str]:
    return {'hello': 'rapidy'}

@middleware
async def auth_middleware_1(request: Request, call_next: CallNext) -> StreamResponse:
    # auth logic 1 ...
    print('auth 1 ...')
    return await call_next(request)

@middleware
async def auth_middleware_2(request: Request, call_next: CallNext) -> StreamResponse:
    # auth logic 2 ...
    print('auth 2 ...')
    return await call_next(request)

router_auth_1 = HTTPRouter('/v1', [hello_handler], middlewares=[auth_middleware_1])
router_auth_2 = HTTPRouter('/v2', [hello_handler], middlewares=[auth_middleware_2])

api_router = HTTPRouter('/api', [router_auth_1, router_auth_2])

rapidy = Rapidy(http_route_handlers=[api_router])

HTTPRouter Attributes

path

path: str — the handler's route on the server.

from rapidy.http import HTTPRouter

router = HTTPRouter(
    path='/api',
)

---

route_handlers

route_handlers: Iterable[BaseHTTPRouter] = () — a list of route handlers. It can include both individual handlers and nested HTTPRouter instances.

from rapidy.http import get, HTTPRouter

@get('/hello')  # /api/hello
async def hello_handler() -> str:
    return 'hello rapidy!'

router = HTTPRouter(
    path='/api',
    route_handlers=[hello_handler],
)

---

middlewares

middlewares: Optional[Iterable[Middleware]] = None — a list of middleware applied to all handlers, including child routers.

from rapidy.http import middleware, Request, StreamResponse, HTTPRouter
from rapidy.typedefs import CallNext

@middleware
async def hello_middleware(request: Request, call_next: CallNext) -> StreamResponse:
    print('hello')
    return await call_next(request)

router = HTTPRouter(
    path='/api',
    middlewares=[hello_middleware],
)

Read more about Middlewares here.

---

client_max_size

client_max_size: int = 1024**2 — The maximum request size in bytes.

from rapidy.http import HTTPRouter

router = HTTPRouter(
    path='/api',
    client_max_size=1000,
)

---

Lifecycle Management

HTTPRouter supports lifecycle management just like the main application.

Read more about Lifespan here.

on_startup

on_startup: Optional[List[LifespanHook]] — a list of tasks executed when the application starts.

from rapidy.http import HTTPRouter

async def startup() -> None:
    print('startup')

router = HTTPRouter(
    path='/api',
    on_startup=[startup],
)

---

on_shutdown

on_shutdown: Optional[List[LifespanHook]] — tasks executed when the server shuts down.

from rapidy.http import HTTPRouter

async def shutdown() -> None:
    print('shutdown')

router = HTTPRouter(
    path='/api',
    on_shutdown=[shutdown],
)

---

on_cleanup

on_cleanup: Optional[List[LifespanHook]] — tasks executed after on_shutdown.

from rapidy.http import HTTPRouter

async def cleanup() -> None:
    print('cleanup')

router = HTTPRouter(
    path='/api',
    on_cleanup=[cleanup],
)

---

lifespan

lifespan: Optional[List[LifespanCTX]] = None — a list of context managers that support application lifecycle management.

from contextlib import asynccontextmanager
from typing import AsyncGenerator
from rapidy import Rapidy
from rapidy.http import HTTPRouter

@asynccontextmanager
async def bg_task(rapidy: Rapidy) -> AsyncGenerator[None, None]:
    try:
        print('starting background task')
        yield
    finally:
        print('finishing background task')

router = HTTPRouter(
    path='/api',
    lifespan=[bg_task],
)