- 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>
17 KiB
paths
| paths | ||||
|---|---|---|---|---|
|
Контракт API: что требуют smoke и защита
Источники: contracts/openapi.json (пути, схемы, коды),
contracts/README.md (семантика; приоритет над поведением библиотек,
кроме согласованных расхождений FastAPI — раздел ниже), рубрика в
README.md. Сгенерированная FastAPI схема (/openapi.json) — только
справка, сверять с контрактом. Если контракт противоречит сам себе —
спросить пользователя. Ниже то, что легко нарушить.
FastAPI: что разрешено и что всё равно ловит smoke
Преподаватель 2026-09-26 разрешил FastAPI с его расхождениями: лишний
422 и другой порядок кодов ошибок (AGENTS.md, «Согласования с
преподавателем»). Публичный smoke это не отменяет: на каждый ответ
≥ 400 он проверяет и статус, и тело {"error": ...}. Проверено на
FastAPI 0.141 из uv.lock:
| Запрос | FastAPI по умолчанию | Smoke ждёт |
|---|---|---|
GET /api/v1/users/me без Authorization, заголовок объявлен Header() |
422 | 401 |
POST .../messages с {"text": ""} |
422 | 400 |
GET .../messages?limit=0 |
422 | 400 |
| любая ошибка | {"detail": ...} |
формат контракта |
- Один обработчик
RequestValidationError→ 400invalid_requestв формате контракта. Оставлять 422 выборочно сложнее, чем перевести всё, поэтому 422 не отдаётся вообще. Authorizationне объявлять типизированнымHeader(): пропуск уйдёт в валидацию и даст 400 вместо 401. Схемы безопасности — те же, что в контракте (bearerAuth,basicAuth): тогда они есть в/openapi.json, а в/docsработает кнопка Authorize.- Бизнес-ручки:
HTTPBearer(scheme_name="bearerAuth", auto_error=False)вget_current_user. Без заголовка или со схемой неBearerона отдаётNone, и 401 бросает сервис. - Вход: встроенный
HTTPBasicне годится даже сauto_error=False. Он декодирует credentials как ASCII и на пароле не из ASCII сам бросает 401, минуя сервис (проверено на FastAPI 0.141.1), а контракт требует UTF-8. СхемаbasicAuthобъявляется, но заголовок разбирается своим кодом (auth.md).
- Бизнес-ручки:
- Порядок проверок не выправлять, это и есть разрешённое расхождение.
Битый JSON FastAPI разбирает до зависимостей, поэтому запрос без
Authorizationс битым JSON получит 400, а не 401. Остальная валидация (тело, путь, query) идёт после зависимостей, там 401 приходит первым. Расхождение перечислить вREPORT.mdсо ссылкой на согласование. StarletteHTTPException(404 неизвестного пути, 405) иException(500) тоже переводятся в формат контракта.
Формат ответов
- Непустой
X-Request-Idв каждом ответе: успех, ошибка, health, 404 неизвестного пути, 405, 500. С лабы 3 так же — непустойX-Instance-Id(раздел «Балансировка и повторная отправка» ниже): smoke проверяет его на каждом ответе, начиная с/health/live. - Любая ошибка:
{"error": {"code": ..., "message": ..., "request_id": ...}}сContent-Type: application/json, иrequest_idсовпадает с заголовком. Лишних полей нет (additionalProperties: false). message— короткий текст для человека на английском (язык контракт не задаёт, русский текст вcontracts/examples.json— только пример). В нём нет stack trace, путей к файлам, имён классов, SQL и признаков существования чужого объекта. Источник текста —default_messageдоменного исключения или общий текст обработчика вerrors.py.- Обработчики
RequestValidationError,StarletteHTTPExceptionиExceptionпереопределяются вsrc/api/errors.py(раздел «FastAPI» выше).
| Статус | code |
Когда |
|---|---|---|
| 400 | invalid_request |
тело, UUID, limit, cursor, malformed JSON, лишнее поле, неверный тип; с лабы 3 — нет или неверный Idempotency-Key у POST сообщения |
| 401 | unauthorized |
вход: неверные username или пароль, битый Basic; остальное: нет Bearer, токен неизвестен, истёк или отозван, пришёл Basic. Всегда с WWW-Authenticate (auth.md) |
| 404 | not_found |
объекта нет или он чужой; неизвестный путь |
| 409 | conflict |
username занят; с лабы 3 — тот же Idempotency-Key с другим телом сообщения |
| 500 | internal_error |
необработанное исключение, без деталей |
| 503 | unavailable |
недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (infra.md) |
413, 415, 429 в схеме есть, но на лабе 3 обязательной причины для
них нет. Для 429 нужен Retry-After. DELETE /auth/sessions/current
отвечает 204 без тела.
- Время — RFC 3339 UTC с
Z, назначает сервер. Формат отдавать явно черезsrc/utils/utc.py, а не полагаться на сериализацию по умолчанию: smoke требует окончаниеZ. created_atхранится и отдаётся с одной точностью (микросекунды). Иначе порядок, который видит клиент, разойдётся с порядком курсора.GET /health/live→ 200{"status": "ok"}.GET /health/ready→ 200{"status": "ok"}или 503 в формате ошибки: 200 только если доступен Postgres и всё, без чего не работает обязательный путь (infra.md). Обе без идентификации.
Валидация → 400
- Модели запросов:
extra="forbid"и строгие типы на уровне полей (StrictStr,StrictInt), чтобы число не превращалось в строку, а лишнее поле давало 400.ConfigDict(strict=True)на всю модель не ставить: FastAPI валидирует тело как Python-объект, и strict-режим отвергает UUID, пришедший строкой (проверено: корректныйmember_idsдаёт 422). Query-параметры остаются нестрогими:limit=5приходит строкой. - Malformed JSON и не-объект вместо объекта → 400. FastAPI отдаёт их как
422
json_invalid, это переводится общим обработчиком. - Обязательные строки (
display_name,title,text,password) не могут состоять только из пробельных символов (str.strip()пустой → 400). Само значение не обрезать. - Длины считаются в Unicode code points:
len(str)в Python как раз они.display_nameиtitle— 1–100,text— 1–4000,password— 12–128. username— строго^[a-z0-9_]{3,32}$на всю строку. В ручной проверкеre.fullmatch:re.matchс$пропускает\nв конце.- Лишнее поле
sender_idв теле сообщения → 400: отправитель выводится из текущего пользователя. chat_idне UUID → 400.limit— целое 1–100, по умолчанию 50;limit=0и нечисловой → 400. Битыйcursor→ 400.member_ids: 1–100 элементов, без дубликатов, все пользователи существуют, вызывающий в списке. Иначе 400.
Аутентификация и сессии (лаба 2)
Переход 1 → 2 (COURSE.md): регистрация требует password,
X-User-Id заменён Bearer. Реализация — auth.md.
- Без аутентификации — только
POST /api/v1/usersи health.POST /api/v1/auth/sessionsпринимает толькоAuthorization: Basic, без JSON-тела, и отвечает201 Session. Всё остальное, включаяDELETE /api/v1/auth/sessions/current, принимает толькоAuthorization: Bearer <token>. - Basic на бизнес-ручке — 401 с вызовом Bearer: smoke шлёт верный Basic
на
GET /users/meи ждёт 401. X-User-Idигнорируется: доступа не даёт и владельца сессии не меняет. Smoke шлёт Bearer alice вместе сX-User-Ideve и ждёт alice.- Сначала аутентификация, потом доступ: без токена — 401 даже на чужой чат. Чужой и несуществующий чат дают одинаковый 404, 403 не используется.
- В
Userнет пароля, его хэша и данных сессии. - Logout — 204 без тела; тот же токен после него — 401.
Чаты и сообщения
- Чат создаётся атомарно.
GET /api/v1/chatsвозвращает только чаты текущего пользователя, по(created_at, id)по возрастанию, сlimit/cursor, как история. - Любой участник читает чат и историю и пишет в чат. Посторонний
получает 404 на
GETчата, историю иPOSTсообщения.
Пагинация (keyset)
- Порядок
(created_at, id)по возрастанию.idсравнивается как UUID (uuid.UUID(x).int) — так же сортирует smoke. - Ответ:
{"items": [...], "next_cursor": null | "..."}.next_cursorравен null, когда следующей записи нет на момент чтения. Страница ровно изlimitэлементов при пустом остатке тоже даёт null, поэтому repo выбираетlimit + 1. - Курсор непрозрачный (
src/utils/cursor.py): ключ последнего элемента плюс область — чат или список чатов пользователя. Курсор другого чата или пользователя, битая base64 или JSON → 400. Последний элемент предыдущей страницы не повторяется.limitмежду страницами можно менять. - Семантику при конкурентных вставках и ограничения часов описать в
REPORT.md(например:created_atмонотонен внутри чата). - В Postgres порядок и курсор задаёт SQL: сравнение кортежей
(created_at, id)по индексу(chat_id, created_at, id), безOFFSET(repo-layer.md).uuidPostgres сравнивает побайтно, это тот же порядок, чтоUUID.int.
Сохранность (с лабы 2)
Пользователи, чаты, участники, сообщения и ещё действующие сессии
переживают рестарт API и всех хранилищ с сохранёнными volumes: тот же
токен после рестарта читает те же данные. TTL из-за рестарта не
продлевается. Проверка — make test-persistence ACTION_SCRIPT=scripts/restart.sh (tests/README.md), hook —
docker.md. Подтверждённое сообщение видно следующему чтению через
любую реплику: история не кэшируется, кэш карточки чата не отдаёт
устаревших данных (состав чата неизменен).
Балансировка и повторная отправка (лаба 3)
Переход 2 → 3 (COURSE.md): Idempotency-Key обязателен для отправки
сообщения, ответы API содержат X-Instance-Id. Семантика —
contracts/README.md, раздел «Балансировка и повторная отправка».
Реализация — api-layer.md (заголовки), service-layer.md
(транзакция), balancer.md (стенд).
X-Instance-Id— в каждом ответе, созданном API: успех, ошибки, health, 404 неизвестного пути, 405, 500. Значение стабильно, пока жив процесс, и одно на процесс. Ответ, который сгенерировал сам HAProxy (502/503/504 при недоступных репликах), заголовка может не иметь — контракт это допускает.Idempotency-Key— только уPOST /api/v1/chats/{chat_id}/messages, ASCII^[A-Za-z0-9._:-]{1,128}$на всю строку. Нет ключа или он неверный — 400invalid_request. Smoke:POSTбез ключа от участника — 400. ДругиеPOSTключ не требуют и не обрабатывают.- Область уникальности — пользователь + метод + путь чата + ключ.
Ключ принимает одна ручка, поэтому область —
(user_id, chat_id, key). Одинаковый ключ у разных пользователей или в разных чатах — независимые сообщения. - Повтор того же тела в течение 24 ч (
IDEMPOTENCY_TTL_SECONDS, у нас[idempotency] ttl_seconds) — тот же 201 и то жеMessage: тот жеid,created_atдо микросекунды, тот же текст. Smoke сравнивает JSON целиком (replay == first). «То же тело» — семантически: порядок ключей JSON не важен, отсутствующийattachment_idsравен[](с лабы 4). Другое тело с тем же ключом — 409conflict. - Повтор заново проверяет сессию и доступ: отозванный токен — 401, посторонний — 404, даже если ключ уже сохранён.
- Конкурентные повторы через разные реплики создают ровно одно сообщение; все успешные ответы одинаковы. Транзиентная ошибка (5xx, отказ БД) результатом не фиксируется: ключ и сообщение пишутся в одной транзакции, откат убирает оба.
- Порядок кодов: ключ объявлен параметром ручки (
Header), а FastAPI проверяет параметры и тело после зависимостей (раздел «FastAPI»). Значит, ожидаемый порядок — 401 (сессия) → 400 (ключ, тело) → 404 (не участник) → 409 (другое тело). Исключение то же, что везде: битый JSON — 400 раньше 401. Порядок закрепить тестом вstudent-tests/, а не считать доказанным. - Прозрачных повторов других
POSTнет ни в API, ни в LB: создание чата или регистрация при повторе создали бы второй объект (balancer.md, повторы LB только на отказ соединения).