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

98 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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`.