diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 1c388eb8..d55f28b3 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -120,6 +120,16 @@ FastAPI 0.141 из `uv.lock`: `limit=0` и нечисловой → 400. Битый `cursor` → 400. - `member_ids`: 1–100 элементов, без дубликатов, все пользователи существуют, вызывающий в списке. Иначе 400. +- UUID на входе — только запись 8-4-4-4-12 (`format: uuid`), цифры в + любом регистре (спек `api-conventions`, «UUID на входе»). `UUID` + pydantic шире контракта: принимает запись без дефисов, с `urn:uuid:` и + в `{…}` (проверено на pydantic 2.13). Поэтому всё, что UUID передаёт + клиент, — `chat_id` в пути и элементы `member_ids`, с лабы 4 и + `attachment_ids`, — объявляется типом `UuidIn` из + `src/api/schemas/common.py` (`BeforeValidator` с `UUID_PATTERN` и + `re.fullmatch`), а не голым `UUID`. Модели ответов — обычный `UUID`. + Не-строку `UuidIn` отдаёт валидатору `UUID`, и `[]`, `{}`, `123`, + `false` дают 400 по типу. ## Аутентификация и сессии (лаба 2) @@ -162,6 +172,13 @@ FastAPI 0.141 из `uv.lock`: или пользователя, битая base64 или JSON → 400. Последний элемент предыдущей страницы не повторяется. `limit` между страницами можно менять. +- Курсор принимается только в записи, которую выдал сервер: + `decode_cursor` после разбора собирает его заново (`encode_cursor`) и + сравнивает со входом. Изменённый курсор — `"i"` не строка, тот же id в + другой записи, `"v": true`, лишнее поле — 400, а не 500 и не страница + (спек `pagination`, «Изменённый курсор»). Значения курсора до + `UUID()` и `strptime` проверяются на тип: `UUID()` на не-строке роняет + `AttributeError`, а не `ValueError` (change `strict-id-validation`). - Семантику при конкурентных вставках и ограничения часов описать в `REPORT.md` (например: `created_at` монотонен внутри чата). - В Postgres порядок и курсор задаёт SQL: сравнение кортежей diff --git a/openspec/changes/strict-id-validation/tasks.md b/openspec/changes/strict-id-validation/tasks.md index 84579726..eee7d580 100644 --- a/openspec/changes/strict-id-validation/tasks.md +++ b/openspec/changes/strict-id-validation/tasks.md @@ -87,7 +87,7 @@ - [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков (после подтверждения; сообщение вроде `test: cover tampered cursors and UUID input forms`). Проверка: `git status` чист. -- [ ] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание +- [x] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание (решение 5): - красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201); @@ -99,7 +99,7 @@ ## 3. Исправление (решения 1–2) -- [ ] 3.1 `UUID_PATTERN` (8-4-4-4-12, шестнадцатеричные цифры в любом +- [x] 3.1 `UUID_PATTERN` (8-4-4-4-12, шестнадцатеричные цифры в любом регистре) в `src/utils/constants.py`. В `src/api/schemas/common.py` — тип UUID входа: `Annotated[UUID, BeforeValidator(...)]` с `re.fullmatch`; не-строку пропускает дальше. Проверка: `uv run python @@ -107,12 +107,12 @@ - канон в обоих регистрах принимается; - запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце, `[]`, `{}`, `123`, `false`, `null` — ошибка валидации. -- [ ] 3.2 Тип UUID входа у `member_ids` (`src/api/schemas/chat.py`) и у +- [x] 3.2 Тип UUID входа у `member_ids` (`src/api/schemas/chat.py`) и у `chat_id` трёх ручек (`src/api/routers/v1/chat.py`, `message.py`). Модели ответов не меняются. Проверка: `make run_dev`, в `/openapi.json` у `chat_id` по-прежнему `{"type": "string", "format": "uuid"}`. -- [ ] 3.3 `decode_cursor` (`src/utils/cursor.py`): +- [x] 3.3 `decode_cursor` (`src/utils/cursor.py`): - `t` и `i` — строки; - `except` только `ValueError`; - обратная сборка через `encode_cursor` и сравнение со входом; @@ -121,10 +121,10 @@ Проверка: `uv run python -c` — на всех вариантах 2.1 и на `garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого исключения нет; на выданном курсоре — тот же ключ. -- [ ] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста +- [x] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста реплик пропущены с причиной «one API process». Вывод — в журнал этапа. -- [ ] 3.5 Правило `.claude/rules/api-contract.md`: +- [x] 3.5 Правило `.claude/rules/api-contract.md`: - «Валидация → 400»: pydantic принимает UUID шире `format: uuid`; вход с UUID (путь и тело) — только через тип UUID входа из `common.py`, ответы — `UUID`; diff --git a/src/api/routers/v1/chat.py b/src/api/routers/v1/chat.py index 45bc8f34..335c460f 100644 --- a/src/api/routers/v1/chat.py +++ b/src/api/routers/v1/chat.py @@ -1,9 +1,7 @@ -from uuid import UUID - from fastapi import APIRouter from src.api.dependencies import ChatServiceDep, CurrentUser, PageQueryDep -from src.api.schemas import Chat, ChatPage, CreateChat +from src.api.schemas import Chat, ChatPage, CreateChat, UuidIn router = APIRouter(prefix="/chats", tags=["chats"]) @@ -39,7 +37,7 @@ async def list_chats( @router.get("/{chat_id}", response_model=Chat) async def get_chat( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, chats: ChatServiceDep, ) -> Chat: chat = await chats.get_chat_for_member(chat_id=chat_id, user_id=user.id) diff --git a/src/api/routers/v1/message.py b/src/api/routers/v1/message.py index 069235dd..4ebf3a44 100644 --- a/src/api/routers/v1/message.py +++ b/src/api/routers/v1/message.py @@ -1,10 +1,9 @@ from typing import Annotated -from uuid import UUID from fastapi import APIRouter, Header from src.api.dependencies import CurrentUser, MessageServiceDep, PageQueryDep -from src.api.schemas import CreateMessage, Message, MessagePage +from src.api.schemas import CreateMessage, Message, MessagePage, UuidIn from src.utils.constants import ( IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_MAX_LENGTH, @@ -31,7 +30,7 @@ IdempotencyKeyHeader = Annotated[ @router.post("", status_code=201, response_model=Message) async def send_message( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, body: CreateMessage, idempotency_key: IdempotencyKeyHeader, messages: MessageServiceDep, @@ -49,7 +48,7 @@ async def send_message( @router.get("", response_model=MessagePage) async def list_messages( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, page: PageQueryDep, messages: MessageServiceDep, ) -> MessagePage: diff --git a/src/api/schemas/__init__.py b/src/api/schemas/__init__.py index cec9a6e1..fe1a3616 100644 --- a/src/api/schemas/__init__.py +++ b/src/api/schemas/__init__.py @@ -1,5 +1,5 @@ from .chat import Chat, ChatPage, CreateChat -from .common import Error, ErrorBody, ErrorCode, Health +from .common import Error, ErrorBody, ErrorCode, Health, UuidIn from .message import CreateMessage, Message, MessagePage from .session import Session from .user import CreateUser, User @@ -18,4 +18,5 @@ __all__ = [ "MessagePage", "Session", "User", + "UuidIn", ] diff --git a/src/api/schemas/chat.py b/src/api/schemas/chat.py index 33f3f265..db34bcf6 100644 --- a/src/api/schemas/chat.py +++ b/src/api/schemas/chat.py @@ -2,7 +2,7 @@ from uuid import UUID from pydantic import BaseModel, ConfigDict, Field -from src.api.schemas.common import NonBlankStr, UtcDatetime +from src.api.schemas.common import NonBlankStr, UtcDatetime, UuidIn from src.utils.constants import ( CHAT_MEMBERS_MAX, CHAT_MEMBERS_MIN, @@ -20,7 +20,7 @@ class CreateChat(BaseModel): ) # только форма; повторы, существование и вызывающего в списке # проверяет ChatService.create_chat - member_ids: list[UUID] = Field( + member_ids: list[UuidIn] = Field( min_length=CHAT_MEMBERS_MIN, max_length=CHAT_MEMBERS_MAX, ) diff --git a/src/api/schemas/common.py b/src/api/schemas/common.py index 8cf3c5b7..050894a5 100644 --- a/src/api/schemas/common.py +++ b/src/api/schemas/common.py @@ -1,11 +1,20 @@ -"""Общие типы HTTP-моделей: строки, время, ошибки, health.""" +"""Общие типы HTTP-моделей: строки, UUID входа, время, ошибки, health.""" +import re from datetime import datetime from enum import StrEnum from typing import Annotated, Literal +from uuid import UUID -from pydantic import AfterValidator, BaseModel, PlainSerializer, StrictStr +from pydantic import ( + AfterValidator, + BaseModel, + BeforeValidator, + PlainSerializer, + StrictStr, +) +from src.utils.constants import UUID_PATTERN from src.utils.utc import to_rfc3339 @@ -16,9 +25,25 @@ def _reject_blank(value: str) -> str: return value +def _require_uuid_form(value: object) -> object: + """Строка UUID — только в записи 8-4-4-4-12; не-строку разбирает `UUID`. + + pydantic принимает и запись без дефисов, с `urn:uuid:` и в `{…}`, а + контракт — только `format: uuid`. Тип не-строки (массив, число, bool) + отвергает сам валидатор `UUID`. + """ + if isinstance(value, str) and not re.fullmatch(UUID_PATTERN, value): + raise ValueError("must be a UUID in 8-4-4-4-12 form") + return value + + # строгая строка: число не превращается в строку; пробелы не принимаются NonBlankStr = Annotated[StrictStr, AfterValidator(_reject_blank)] +# UUID, который передаёт клиент (путь и тело): запись контракта, цифры в +# любом регистре. Модели ответов — обычный `UUID` +UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)] + # время в ответе: RFC 3339 UTC, всегда шесть знаков микросекунд и Z UtcDatetime = Annotated[ datetime, diff --git a/src/utils/constants.py b/src/utils/constants.py index 92d89d2a..620aa8b4 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -15,6 +15,13 @@ REQUEST_ID_HEADER = "X-Request-Id" INSTANCE_ID_HEADER = "X-Instance-Id" IDEMPOTENCY_KEY_HEADER = "Idempotency-Key" +# идентификатор на входе: запись 8-4-4-4-12 (`format: uuid` контракта), +# шестнадцатеричные цифры в любом регистре +UUID_PATTERN = ( + r"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}" + r"-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" +) + # экземпляр API: значение X-Instance-Id безопасно для заголовка и журнала INSTANCE_ID_PATTERN = r"^[A-Za-z0-9._-]{1,64}$" diff --git a/src/utils/cursor.py b/src/utils/cursor.py index d1cd2a29..1150c4ba 100644 --- a/src/utils/cursor.py +++ b/src/utils/cursor.py @@ -4,6 +4,11 @@ `{"v": 1, "s": <область>, "t": , "i": }`. Область привязывает курсор к конкретному списку: курсор чужого чата или списка чатов другого пользователя не разбирается. + +Принимается только та запись, которую выдал сервер: после разбора курсор +собирается заново и сравнивается с полученной строкой. Так изменённый +клиентом курсор (`"v": true`, лишнее поле, id или время в другой записи) +— ошибка, а не страница. """ import base64 @@ -47,8 +52,9 @@ def encode_cursor(*, scope: str, created_at: datetime, item_id: UUID) -> str: def decode_cursor(cursor: str, *, scope: str) -> CursorKey: """Ключ последнего элемента предыдущей страницы. - Бросает `CursorError`, если курсор не разбирается, другой версии или - выдан для другой области. + Бросает `CursorError`, если курсор не разбирается, другой версии, + выдан для другой области или отличается от записи, которую выдал бы + `encode_cursor` для того же ключа. """ try: padded = cursor + "=" * (-len(cursor) % 4) @@ -63,7 +69,17 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey: if payload.get("s") != scope: raise CursorError("cursor belongs to another list") + raw_time, raw_id = payload.get("t"), payload.get("i") + # не-строку UUID() не отвергает, а роняет AttributeError + if not isinstance(raw_time, str) or not isinstance(raw_id, str): + raise CursorError("malformed cursor") try: - return from_rfc3339(payload["t"]), UUID(payload["i"]) - except (KeyError, TypeError, ValueError) as e: + created_at = from_rfc3339(raw_time) + item_id = UUID(raw_id) + except ValueError as e: raise CursorError("malformed cursor") from e + + issued = encode_cursor(scope=scope, created_at=created_at, item_id=item_id) + if issued != cursor: + raise CursorError("cursor was changed") + return created_at, item_id