- 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>
FastAPI, один процесс на реплику; реплик ≥2 за HAProxy (balancer.md).
Что обязан отдавать HTTP — .claude/rules/api-contract.md; здесь — как
устроен слой.
В памяти процесса нет состояния, от которого зависит ответ: любой
запрос может прийти на любую реплику. Сессии, данные и ключи
идемпотентности — в Postgres; глобалы модулей — только клиенты
хранилищ и неизменяемые значения (instance_id, фиктивный хэш
пароля).
Роутинг
Что
Файл
Путь
health
routers/health.py
/health/live, /health/ready — вне версии, без идентификации, из access-лога исключены
Версию задаёт 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.