Files
mtusi2026lab3/.claude/rules/api-contract.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

17 KiB
Raw Blame History

paths
paths
src/api/**
src/core/**
src/schemas/**
student-tests/**

Контракт 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 → 400 invalid_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-Id eve и ждёт 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). uuid Postgres сравнивает побайтно, это тот же порядок, что 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}$ на всю строку. Нет ключа или он неверный — 400 invalid_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). Другое тело с тем же ключом — 409 conflict.
  • Повтор заново проверяет сессию и доступ: отозванный токен — 401, посторонний — 404, даже если ключ уже сохранён.
  • Конкурентные повторы через разные реплики создают ровно одно сообщение; все успешные ответы одинаковы. Транзиентная ошибка (5xx, отказ БД) результатом не фиксируется: ключ и сообщение пишутся в одной транзакции, откат убирает оба.
  • Порядок кодов: ключ объявлен параметром ручки (Header), а FastAPI проверяет параметры и тело после зависимостей (раздел «FastAPI»). Значит, ожидаемый порядок — 401 (сессия) → 400 (ключ, тело) → 404 (не участник) → 409 (другое тело). Исключение то же, что везде: битый JSON — 400 раньше 401. Порядок закрепить тестом в student-tests/, а не считать доказанным.
  • Прозрачных повторов других POST нет ни в API, ни в LB: создание чата или регистрация при повторе создали бы второй объект (balancer.md, повторы LB только на отказ соединения).