Files
mtusi2026lab3/openspec/changes/strict-id-validation/design.md
T
ricoromaandClaude Opus 5.5 8fe467ace0 fix: check cursor fields instead of re-encoding
628b5f2 accepted a cursor only if re-encoding the parsed key gave the
same string. That closed the format both ways: any encoding change, even
a compatible one (an optional field, key order, to_rfc3339 shared with
API responses), would turn cursors issued by a replica of the other
version into 400 during make rolling_update, which the tests cannot see.

decode_cursor now checks the fields one by one: v must be exactly the
integer 1, t and i must be strings, i must be in the server's notation
(lowercase 8-4-4-4-12). Unknown fields are ignored, so a tampered cursor
is still a 400 while the format stays open for compatible changes. The
rule records how to change the format: a new CURSOR_VERSION, with both
versions accepted while replicas are replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 13:11:57 +03:00

20 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, «Why»; требования — дельты api-conventions («UUID на входе»), pagination («Курсор непрозрачен и привязан к списку»), chats («Создание чата», «Валидация чата»). Контракт валидации — .claude/rules/api-contract.md, «Валидация → 400» и «Пагинация (keyset)».

Код сейчас (HEAD 40f470f):

  • Курсор — src/utils/cursor.py. Это base64url без padding от компактного JSON {"v":1,"s":…,"t":…,"i":…}. decode_cursor по порядку проверяет: base64 и JSON → объект → v == 1 → s == scope → from_rfc3339(t), UUID(i) под except (KeyError, TypeError, ValueError). Сервис переводит CursorError в InvalidCursor → 400 (src/core/services/pagination.py, src/api/errors.py).
  • UUID на входе — три параметра пути chat_id: UUID (src/api/routers/v1/chat.py, message.py) и member_ids: list[UUID] в CreateChat (src/api/schemas/chat.py). Разбирает pydantic 2.13.5.

Проверено до change (пробы в .venv проекта, не замер):

  • decode_cursor на выданном курсоре, где подменено одно поле. Для "i" = [], {}, 123, false получается AttributeError (UUID() вызывает .replace у не-строки), то есть 500. Для "i" = null, "zz" и для "t" любого не-строкового типа — CursorError, то есть 400. Курсор с "v": true или с "i" без дефисов и в верхнем регистре разбирается и даёт страницу.
  • TypeAdapter(UUID) принимает запись 8-4-4-4-12 в любом регистре, а также запись без дефисов, с urn:uuid: и в {…}. С пробелом по краю — нет. list[UUID] отвергает [[]], [{}], [123], [false], [null] (uuid_type), а {}, 123, false и строку вместо списка — list_type.
  • Тип Annotated[UUID, BeforeValidator(...)] с проверкой записи проверен на FastAPI 0.141.1 в отдельном приложении. И в пути, и в элементах тела канон в любом регистре даёт 200, а остальное — ошибку валидации (у нас она станет 400). Схема /openapi.json для пути осталась {"type": "string", "format": "uuid"}.
  • Курсоры строит только сервер. Стенд bench/ (k6) и student-tests/ берут их из next_cursor, сами не собирают.

Goals / Non-Goals

Goals:

  • Никакой ввод в cursor, chat_id и member_ids не даёт 500.
  • Вход с UUID — ровно format: uuid контракта; ответы не меняются.
  • Подменённый курсор — 400. Формат при этом остаётся открытым для совместимых правок: незнакомые поля игнорируются. Формат выдачи прежний: курсоры от реплик до замены работают и после неё.
  • Каждый новый сценарий спека — тест black-box. Тесты курсора и записи UUID красные на текущем коде, это показано в evidence.

Non-Goals:

  • Подпись курсора (HMAC). Решение 3.
  • Повторные замеры bench/. Путь запроса меняется на одну регулярку и одну сериализацию курсора; методика меток к этому не относится.
  • Ужесточение других полей (username, Idempotency-Key, тексты). У них уже есть строгие шаблоны и StrictStr.
  • Полная проверка из чистого clone на портах по умолчанию. Она требует удалить рабочий стенд вместе с volume — только с явного согласия пользователя (решение 6).

Decisions

1. Общий тип UUID входа — BeforeValidator над UUID

В src/api/schemas/common.py появляется тип UUID входа (рабочее имя — UuidIn):

UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)]
  • _require_uuid_form строку, не совпавшую целиком с шаблоном 8-4-4-4-12, отвергает ValueError («must be a UUID in 8-4-4-4-12 form»). Шаблон — UUID_PATTERN в src/utils/constants.py, совпадение — re.fullmatch: re.match с $ пропустил бы \n в конце (та же ловушка, что у username, api-contract.md).
  • Не-строку валидатор пропускает дальше: её тип отвергает сам валидатор UUID (uuid_type). Объект UUID из Python — тоже, это нужно для внутренних вызовов.
  • Где применяется: chat_id во всех трёх ручках и member_ids: list[UuidIn]. Модели ответов остаются на UUID.
Вариант Почему не он
Annotated[str, Field(pattern=…)] и UUID(...) в ручке ручка получает строку; преобразование повторяется в трёх местах, сервис мог бы получить str
Path(pattern=…) у UUID ограничение pattern у не-строкового типа pydantic не принимает
UUID4 / версия UUID проверяет версию, а не запись; запись без дефисов проходит, а id другой версии — нет, хотя контракт говорит просто uuid
strict-режим pydantic строгость по типу, а не по записи: строка без дефисов проходит
AfterValidator видит уже разобранный UUID, исходная запись потеряна

Регистр. RFC 9562 (§4) требует принимать шестнадцатеричные цифры на входе без учёта регистра. Валидаторы format: uuid JSON Schema тоже принимают верхний регистр. Поэтому верхний регистр допустим, а разобранный UUID равен тому же id в нижнем. Повтор [Алиса, АЛИСА] сервис ловит как и раньше: дубликаты он сравнивает по UUID, а не по строке.

Порядок кодов не меняется. Параметры пути и тело FastAPI проверяет после зависимостей: 401 → 400 → 404 → 409. Невалидный путь у POST сообщения не доходит до сервиса, ключ идемпотентности не занимается (сценарий idempotency «Невалидный запрос не занимает ключ»).

2. Курсор — проверка полей, незнакомые поля игнорируются

decode_cursor после разбора base64url и JSON проверяет поля по отдельности:

  1. объект; v — ровно целое 1. Тип проверяется отдельно: bool — подкласс int, и True == 1 прошло бы прежнее сравнение;
  2. s == scope (как сейчас);
  3. t и i — строки (isinstance(..., str)), иначе CursorError. Тогда from_rfc3339 и UUID бросают только ValueError, и except сужается до него;
  4. i — в записи сервера: str(UUID(i)) == i (8-4-4-4-12, нижний регистр). Запись UUID от версии кода не зависит, так что эта проверка формат на будущее не закрывает.

Принимаются, потому что разбираются в тот же ключ:

  • незнакомые поля — игнорируются;
  • пробелы и порядок ключей в JSON;
  • padding =.

Формат, который прежний код не прочтёт (переименованное поле, другой формат времени), — новая версия v. На время make rolling_update новая версия принимает обе: курсор, выданный старой репликой, приходит на новую (правило api-contract.md, «Пагинация (keyset)»).

Вариант Почему не он
Добавить AttributeError в except правка в одно слово, но ловит слишком широко (может скрыть настоящий дефект) и не трогает v: true и другие записи — курсор остаётся «разбирается, значит годен»
Только проверки типов убирает 500, но подменённый курсор (v: true, id в другой записи) по-прежнему даёт страницу — расходится с «изменённый курсор → 400»
Обратная сборка: encode_cursor(...) == cursor первая реализация (628b5f2), заменена в apply по просьбе пользователя (раздел «Пересмотр в apply»)
Отвергать незнакомые поля тот же закрытый формат: необязательное поле нового кода давало бы 400 на старых репликах во время замены
Строгая запись t: to_rfc3339(from_rfc3339(t)) == t связывает курсор с форматом времени ответов API (to_rfc3339 общий). Нестрогая запись времени разбирается в позицию того же списка, вреда нет

3. Без подписи курсора

HMAC сделал бы подмену невозможной, но:

  • меняется формат: курсоры, выданные до make rolling_update, перестают работать на новых репликах;
  • нужен общий секрет реплик: настройка, .env.example, REPORT.md, а с лабы 7 — OpenBao;
  • угрозы нет: область s уже привязывает курсор к своему списку. Подменённый ключ сдвигает позицию только внутри списка, который пользователь и так вправе читать. Требование — 400 вместо 500 и вместо страницы, и проверка полей его выполняет.

4. Тесты: подмена настоящего курсора и некрасный контроль

  • Курсор (test_pagination.py). Хелпер раскодирует выданный next_cursor, меняет одно поле и кодирует так же, как сервер (компактный JSON, base64url без =).
    • Контроль: хелпер без изменений возвращает ту же строку — это утверждение в самом хелпере, и такой курсор даёт 200. Так 400 доказано подменой, а не перекодированием, и тест не зависит молча от формата: другой формат роняет хелпер.
    • Курсор не собирается с нуля: с неверными v или s он отсекается до места дефекта, и тест был бы зелёным без исправления. Ровно так устроен нынешний test_garbage_cursor ({"x":1} останавливается на версии).
    • Варианты → 400: "i" = [], {}, 123, false (сейчас 500), тот же id без дефисов и в верхнем регистре, "v": true и 1.0 (сейчас 200).
    • Варианты → 200 и та же страница: без изменений и с лишним полем (незнакомые поля игнорируются).
    • Оба списка: история (два сообщения, limit=1) и список чатов (два чата, limit=1).
  • member_ids (test_chats.py).
    • Плохой элемент — рядом с id самой Алисы: [alice.id, 123]. Одиночный [123] нарушает ещё и «вызывающий в списке», а эта проверка сервиса тоже даёт 400: тест прошёл бы, даже если бы валидация пропустила число.
    • Отклонённый чат не появился — listed_titles, как в соседних тестах.
  • chat_id в пути (test_api_conventions.py).
    • Значения кодируются явно: urllib.parse.quote(value, safe=""), без расчёта на кодирование путей в httpx.
    • Сообщений не прибавилось: после отклонённого POST с другой записью id история чата не изменилась.
    • Верхний регистр: ответы равны ответам на запись в нижнем регистре.
  • Маркеры. Каждый тест помечен @pytest.mark.spec(...) сценарием дельты (student-tests.md), сверка покрытия видит новые сценарии. tests/ skeleton не трогаем.

5. Красный прогон до исправления — в evidence

Сначала коммитятся тесты без исправления, затем — исправление (оба коммита — после подтверждения пользователя). Прогон тестов на первом коммите (make test_isolated, где образ собран из рабочего дерева) показывает, какие тесты красные и почему:

  • 500 у курсора с "i" не того типа;
  • 200 у подменённого курсора и у UUID в другой записи;
  • 201 у member_ids в другой записи.

Тесты типов member_ids и chat_id должны быть зелёными уже здесь. Если какой-то из них красный, это дефект, и он чинится в этом же change. Вывод — в evidence/tests/strict-id-validation-checks.md вместе с зелёным прогоном.

6. Доставка и регрессия

  • Рабочий стенд. Новый код доходит до реплик через make rolling_update. Затем make test и make student_test через LB. make failure_checks не меняется по коду, но сверка покрытия в нём та же, поэтому его тоже прогоняем: один прогон, без параллельных (student-tests.md).
  • Чистый clone. Проверка из чистого clone повторяется во временном проекте compose на нестандартных портах, как evidence/replicas/clean-clone-ports.md: так рабочий стенд и его данные не затрагиваются. Полная проверка на портах по умолчанию (evidence/tests/clean-clone-final.md) удаляет рабочий стенд с volume и поэтому — только по явному согласию пользователя.
  • Откат. make rolling_update COMMIT=<прежний>. Схема БД не менялась, MIGRATE=0 не нужен.

Risks / Trade-offs

  • [Клиент шлёт UUID без дефисов или с urn:uuid:] → теперь 400. Smoke, наши тесты и k6 стенда шлют только id из ответов сервера. Это расхождение с прежним поведением называем в REPORT.md.
  • [Окно поочерёдной замены] → старая реплика ещё принимает нестрогую запись, новая — уже нет. Курсоры одинаковы, данные те же. Окно — секунды, и такого ввода никто не шлёт.
  • [Тест курсора знает его внутренний формат] → если формат изменится, упадёт контрольное утверждение хелпера, и тест покраснеет, а не пройдёт молча. Формат меняют вместе с тестом.
  • [Несовместимая правка формата курсора] → новая v, на время замены реплик принимаются обе (правило api-contract.md). Тесты этого окна не проверяют: курсор в них выдаёт и проверяет один код.
  • [Текст ошибки] → 400 содержит место и сообщение pydantic (path.chat_id: Value error, must be a UUID in 8-4-4-4-12 form) без входного значения — как у остальных ошибок валидации (errors.py).

Пересмотр в apply

Первая реализация курсора (628b5f2) — обратная сборка: разобранный курсор собирался заново через encode_cursor и сравнивался со входом. Подсказка бокового агента указала цену этого решения, и пользователь попросил смягчить:

  • Формат закрыт в обе стороны. Любая правка кодирования, даже совместимая, ломает курсоры реплики другой версии. Совместимые правки — необязательное поле, порядок ключей, to_rfc3339: он общий с форматом времени в ответах.
  • Ломается во время make rolling_update. Клиент листает историю, следующую страницу отдаёт реплика другой версии, и он получает 400. Тесты этого не ловят: курсор в них выдаёт и проверяет один код.
  • Выигрыш почти нулевой. Подменённый, но разбираемый курсор указывает на позицию в списке, который пользователь и так вправе читать. Контракт требует только «битый курсор → 400» и «курсор другого чата → 400». Строгость «только запись сервера» в сценарии спека появилась при propose, рецензент её не просил.

Заменено решением 2: проверка полей, незнакомые поля игнорируются. Из сценария «Изменённый курсор» убрано «добавляет поле → 400», добавлено «с добавленным незнакомым полем — 200 и та же страница». В правило — как менять формат: новая v, на время замены принимаются обе.