Skip to content

feature.md

Latest commit

 

History

History
143 lines (102 loc) · 9.73 KB

feature.md

File metadata and controls

143 lines (102 loc) · 9.73 KB
Raw

Чего не хватает до «полноценного» веб-фреймворка (ресерч)

Документ фиксирует разрыв между текущим OxyRoute (RSGI + Rust hot path, см. index) и ожиданиями от широкого HTTP-фреймворка уровня FastAPI / Starlette / Django REST. Термин «полноценный» здесь означает покрытие типичного продакшн-API и DX, а не обязательность всех пунктов для твоего позиционирования.

Текущий контекст: документация ниже описывает состояние ветки v0.3.x: OxyRoute теперь RSGI-only, ASGI bridge удалён, native RSGI WebSocket реализован, а часть пунктов из старого research уже закрыта. Для практического использования см. usage.md.

Уже есть (кратко)

  • Маршрутизация по методам и путям (matchit), path/query/json/body, 405 / Allow, HEAD на GET, OPTIONS.
  • JWT (HS/RS/… через jsonwebtoken), iss/aud/leeway, cookie, зависимости с request, линейный порядок, freeze.
  • Response / dict с заголовками и cookies, частичный OpenAPI, Pydantic/schema для тела.
  • Один pre-route middleware (set_middleware).
  • Native RSGI WebSocket (@app.websocket, oxyroute.WebSocket), SSE helper.
  • CI, PyPI, E2E/bench harness для Granian RSGI.

Ниже — то, чего нет или что слабо относительно «больших» фреймворков.

1. Протокол и транспорт

Тема Зазор Комментарий
WebSockets Реализованы Native RSGI WebSocket: @app.websocket(path), oxyroute.WebSocket; см. websocket.md. Нет high-level subprotocol API.
SSE / длинный стрим ответа Частично Есть send_sse (см. streaming.md); инкрементальный стрим использует response_stream Granian RSGI.
HTTP/2 push, trailers Не в фокусе Обычно на стороне сервера; фреймворк редко экспонирует.
ASGI совместимость Удалена в v0.3.0 Поддерживается только RSGI (Granian --interface rsgi).

2. Запрос и тело

Тема Зазор Комментарий
multipart/form-data Частично read_form_body=True, инжект form / files (в памяти); см. handlers. #47.
application/x-www-form-urlencoded (body) Частично То же — form; нет streaming для очень больших тел.
Streaming request body Ограничено Тело читается в буфер для JSON/сырых байт; большие upload без полного чтения — отдельная работа.
Валидация на уровне фреймворка Частично Pydantic удобнее вручную; нет единого Body() как в FastAPI для всех типов контента.

3. Маршрутизация и композиция

Тема Зазор Комментарий
Sub-routers / include_router Частично APIRouter, App.include_router — routing, #46.
Mount / static files Нет Отдача /static из каталога — обычно отдельный слой (nginx) или Starlette StaticFiles.
Host-based routing Нет
Глобальные exception handlers Частично HTTPException → нужный статус/JSON (см. handlers); нет register_exception_handler / иерархии как в FastAPI — #48.
Middleware-цепочка Один хук Нет порядка нескольких middleware и on_request / on_response как в ASGI-стеке.

4. Безопасность (кроме JWT)

Тема Зазор Комментарий
CORS CORSConfig + apply_cors / set_cors Preflight и заголовки на ответах; см. cors.md.
CSRF CSRFConfig / apply_csrf / csrf_layer См. csrf.md; double-submit, для Bearer-only API чаще не нужен.
Rate limiting Нет
Security headers (HSTS, CSP, …) SecurityHeadersConfig + set_security_headers security-headers.md; merge не перезаписывает уже заданные в Response имена.
JWKS / ротация ключей Частично В бэклоге #8.

5. Состояние приложения и сессии

Тема Зазор Комментарий
Встроенный app.state / lifespan Частично App.state (SimpleNamespace), хуки __rsgi_init__ / __rsgi_del__, пример examples/rsgi_lifespan_app.py — закрыто в #18.
Сессии (signed cookie, server-side) Нет
Кэш глобальных настроек Нет Нет первого класса для config.

6. Разработка и тестирование

Тема Зазор Комментарий
TestClient (как Starlette/FastAPI) Нет Тесты через in-process RSGI shims или реальный Granian; нет единого обёрточного клиента из коробки.
CLI (oxyroute dev, scaffold) Нет
OpenAPI генерация клиентов Частично Документ есть; не обещается полная совместимость со всеми генераторами.
Background tasks Нет Нет BackgroundTasks после ответа; только внешний воркер/очередь.

7. Наблюдаемость

Тема Зазор Комментарий
Structured access log Зависит от Granian Нет формата «как у фреймворка».
Metrics (Prometheus) Нет
Tracing (OpenTelemetry) Нет

8. Экосистема и позиционирование

  • ORM / миграции — не часть HTTP-фреймворка; обычно SQLAlchemy + Alembic отдельно.
  • Шаблоны HTML (Jinja) — нет; для API не критично.
  • GraphQL / gRPC — отдельные стеки.

OxyRoute осознанно уже в нише: быстрый RSGI HTTP/WebSocket слой с routing, JSON/form/JWT/headers на Rust hot path и Python business logic. «Полноценность» для многих команд теперь упирается меньше в протокол, а больше в стриминг тела запроса, цепочку middleware, TestClient, observability, rate limit и production security automation.

Приоритизация (рекомендация)

  1. Streaming / early body limiting — сейчас body и multipart читаются в память.
  2. Middleware chain — сейчас один pre-route hook, compose вручную.
  3. TestClient — единый удобный клиент поверх RSGI shim.
  4. Observability — metrics/tracing/access-log story.
  5. Exception handlers (глобальные) — удобный слой поверх текущего HTTPException.
  6. JWKS / key rotation — production auth удобство.

Связанные GitHub-issues и исторический backlog

Композиция и тело / ошибки / CORS

  • #46 — sub-routers (21.md)
  • #47 — multipart / urlencoded (22.md)
  • #48 — глобальные исключения / HTTPException (23.md)

Протокол и безопасность

← Documentation index