Files
mtusi2026lab3/.claude/rules/api-layer.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +03:00

6.8 KiB
Raw Blame History

paths
paths
src/api/**
src/main.py

Слой API (src/api/, src/main.py)

FastAPI, один процесс на реплику; реплик ≥2 за HAProxy (balancer.md). Что обязан отдавать HTTP — .claude/rules/api-contract.md; здесь — как устроен слой.

  • В памяти процесса нет состояния, от которого зависит ответ: любой запрос может прийти на любую реплику. Сессии, данные и ключи идемпотентности — в Postgres; глобалы модулей — только клиенты хранилищ и неизменяемые значения (instance_id, фиктивный хэш пароля).

Роутинг

Что Файл Путь
health routers/health.py /health/live, /health/ready — вне версии, без идентификации, из access-лога исключены
ручки v1 routers/v1/<domain>.py /api/v1/<prefix>/...
  • Модуль домена: router = APIRouter(prefix="/users", tags=["users"]). Вложенный ресурс — префикс с параметром: message.py → prefix="/chats/{chat_id}/messages". Логгер модуля module="api_<domain>_router".
  • Версию задаёт v1_router (API_V1_PREFIX из src/utils/constants.py) в routers/v1/__init__.py. Регистрация домена — импорт и v1_router.include_router(...) там, больше нигде.
  • src/main.py: app = FastAPI(...), lifespan, middlewares, обработчики ошибок (errors.register(app)), include_router для health и v1_router. src/__init__.py пустой: импорт любого модуля src не должен поднимать приложение.
  • Новая версия API — пакет routers/v2/ рядом с v1, v1 не ломать.

Внутри ручки

  • Ручки и зависимости — только async def: драйвер БД асинхронный, а синхронная def ушла бы в threadpool. CPU-тяжёлую работу (KDF пароля) явно выносят в поток (auth.md).
  • Ручка: зависимости → вызов сервиса именованными аргументами → DTO в модель ответа (UserOut.model_validate(dto), у модели from_attributes=True). Логики, импортов repo и хранилища здесь нет.
  • Текущий пользователь — Depends(get_current_user) из dependencies.py, по Bearer-токену (auth.md). Сервис — зависимость-фабрика (Depends(get_chat_service)), которая собирает его из AsyncSession. Сессию БД открывает get_db_session из глобального session_factory (src/infra/db/session.py): одна на запрос, закрывается после ответа, вся работа с БД ограничена сроком, отказ БД — 503 (infra.md). Commit делает сервис (service-layer.md).
  • Ошибки — доменные исключения из сервиса. HTTPException не бросать. Статус, code и заголовки ответа (WWW-Authenticate у 401) назначает одна таблица в errors.py.
  • Модели запросов и ответов — src/api/schemas/<domain>.py, имена по схемам контракта (CreateUser, User, ChatPage...). В сервис модели API не передавать: разбирать в именованные аргументы или Create<Entity>DTO.
  • POST создания — status_code=201 в декораторе; response_model — модель контракта.
  • Idempotency-Key (лаба 3) — параметр ручки POST сообщения: Annotated[str, Header(alias="Idempotency-Key", pattern=..., max_length=128)], шаблон — константа в src/utils/constants.py. Так он есть в /openapi.json, а отсутствие и неверный формат дают 400 через общий обработчик валидации. В сервис ключ уходит именованным аргументом вместе с телом; повтор с тем же ключом отвечает тем же 201, что и первый вызов (api-contract.md).

Middlewares и обработчики ошибок

  • Request id: генерируется на каждый запрос, пишется в contextvar логгера и в request.state.request_id и ставится заголовком X-Request-Id в ответ.
  • 500 от необработанного исключения формирует ServerErrorMiddleware. Он стоит снаружи пользовательских middleware, и заголовок из них в этот ответ не попадёт. Поэтому обработчик Exception в errors.py сам берёт id из request.state и ставит заголовок. Сам он не логирует: Starlette после ответа повторно бросает исключение, и traceback пишет uvicorn (logging.md).
  • Итоговая запись о запросе — одна строка: метод, полный шаблон пути, статус, длительность. Без тела, заголовков идентификации и query. Логи uvicorn access выключены (access_log=False), чтобы не было дублей.
  • Полный шаблон пути не брать из scope["route"].path: с FastAPI 0.137 роутеры включаются деревом, и там путь без префикса include_router (/chats/{chat_id} вместо /api/v1/chats/{chat_id}). Источник — таблица из публичного iter_route_contexts(app.routes) в request_context.py. Структуру роутеров ради логов не менять.
  • X-Instance-Id (лаба 3) ставит тот же middleware, что и X-Request-Id, на каждый ответ, включая health, 404 и 405. Значение — settings.app.instance_id (по умолчанию hostname процесса, в compose — короткий ID контейнера), вычисляется один раз при старте. Ответ 500 собирает ServerErrorMiddleware снаружи пользовательских middleware, поэтому обработчик Exception в errors.py ставит и этот заголовок сам, как X-Request-Id.