HTTPRouter

Описание

HTTPRouter позволяет регистрировать группы обработчиков и играет ключевую роль в маршрутизации (routing), направляя запросы к нужным обработчикам в зависимости от HTTP-метода, пути, параметров и других условий.

HTTPRouter регистрируется так же, как и любой HTTP-обработчик.

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 не поддерживает регистрацию обработчиков в стиле aiohttp.

Ни один из способов регистрации обработчиков в стиле aiohttp работать не будет.

Если вам нужно зарегистрировать HTTP-обработчик в HTTPRouter, пользуйтесь методами модуля rapidy.http (get, post, ...).

Вложенные маршрутизаторы (HTTPRouter)

HTTPRouter можно вкладывать друг в друга, что позволяет создавать модульные приложения.

Это полезно, например, для версионирования API.

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

Каждому HTTPRouter можно передать собственные middleware.

Это позволяет, например, применять разные механизмы авторизации для разных групп маршрутов.

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

path

path: str — маршрут обработчика на сервере.

from rapidy.http import HTTPRouter

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

---

route_handlers

route_handlers: Iterable[BaseHTTPRouter] = () — список обработчиков маршрутов. Может включать как отдельные обработчики, так и вложенные HTTPRouter.

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 — список middleware, которые применяются ко всем обработчикам, включая дочерние маршрутизаторы.

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

Подробнее про Middlewares можно прочитать здесь.

---

client_max_size

client_max_size: int = 1024**2 — Максимальный размер запроса в байтах.

from rapidy.http import HTTPRouter

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

---

Управление жизненным циклом

HTTPRouter поддерживает управление жизненным циклом так же, как и основное приложение.

Подробнее про Lifespan можно прочитать здесь.

on_startup

on_startup: Optional[List[LifespanHook]] — список задач, запускаемых при старте приложения.

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]] — задачи, выполняемые при остановке сервера.

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]] — задачи, выполняемые после 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 — список контекстных менеджеров, поддерживающих управление жизненным циклом приложения.

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