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>
20 KiB
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 проверяет поля по
отдельности:
- объект;
v— ровно целое1. Тип проверяется отдельно:bool— подклассint, иTrue == 1прошло бы прежнее сравнение; s == scope(как сейчас);tиi— строки (isinstance(..., str)), иначеCursorError. Тогдаfrom_rfc3339иUUIDбросают толькоValueError, иexceptсужается до него;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, как в соседних тестах.
- Плохой элемент — рядом с id самой Алисы:
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, на время замены принимаются обе.