Files
mtusi2026lab3/openspec/changes/strict-id-validation/proposal.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

6.3 KiB
Raw Blame History

Proposal

Why

Рецензия лабы 3 нашла дефект: повреждённый курсор даёт 500 вместо 400 (src/utils/cursor.py:67). Если в выданном сервером курсоре заменить ключ элемента "i" на [], {}, 123 или false, UUID(...) бросает AttributeError. Этого исключения нет среди перехватываемых, и запрос уходит в общий обработчик 500. Рецензент попросил ещё тесты на те же значения вместо UUID.

Разбор показал, что и остальной вход с UUID шире контракта:

  • pydantic принимает UUID без дефисов, с префиксом urn:uuid: и в фигурных скобках. Так GET /chats/<32 hex> отвечает 200, а member_ids: ["urn:uuid:…"] создаёт чат;
  • контракт объявляет chat_id и элементы member_ids как format: uuid (contracts/openapi.json), contracts/README.md — «неверные … UUID → 400»;
  • курсор после подмены "v": true или записи "i" в другой форме разбирается как настоящий: True == 1, а UUID() из stdlib тоже нестрог.

Пользователь решил чинить всё найденное, чтобы вход совпадал с контрактом и требованиями.

What Changes

  • Подменённый курсор — 400.
    • Значения не того типа больше не роняют разбор.
    • Ключ элемента не строка или не в записи сервера, версия не ровно целое 1 — 400 invalid_request, а не 500 и не 200.
    • Незнакомые поля игнорируются: формат остаётся открытым для совместимых правок, и курсоры не ломаются при поочерёдной замене реплик (design, «Пересмотр в apply»).
  • UUID на входе — только запись 8-4-4-4-12. Это chat_id в пути трёх ручек (GET /chats/{chat_id}, GET и POST /chats/{chat_id}/messages) и элементы member_ids в POST /chats.
    • Шестнадцатеричные цифры принимаются в любом регистре (RFC 9562), в ответах id по-прежнему в нижнем регистре.
    • Без дефисов, с urn:uuid:, в скобках, с пробелами и любой другой тип — 400 invalid_request.
    • BREAKING (для нестандартных клиентов): chat_id и member_ids в записи без дефисов, urn:uuid: или {…} раньше принимались и давали 200 / 201, теперь — 400. Smoke, собственные тесты и k6 стенда bench/ шлют только id, выданные сервером, и это их не задевает.
  • Тесты black-box в student-tests/.
    • Подменённый курсор на обоих списках: история и список чатов.
    • member_ids: [], {}, 123, false вместо UUID, не массив вместо массива, другая запись UUID, верхний регистр.
    • chat_id в пути трёх ручек: те же значения и те же записи.
    • Тесты курсора и записи UUID красные на текущем коде и зелёные после исправления. Тесты типов member_ids уже должны быть зелёными: их сейчас нет, рецензент просил подтвердить поведение.
  • Документы:
    • правило api-contract.md (раздел «Валидация → 400») — где pydantic шире контракта;
    • REPORT.md — таблица доказательств и число тестов;
    • evidence прогонов «до/после».

Capabilities

New Capabilities

Нет.

Modified Capabilities

  • api-conventions: новое требование «UUID на входе»: запись 8-4-4-4-12 без учёта регистра, другие типы и записи — 400; общее для пути и тела.
  • pagination: требование «Курсор непрозрачен и привязан к списку» — изменённый курсор, в том числе с ключом не того типа, — 400, а не 500.
  • chats: «Создание чата» — member_ids в ответе совпадает с переданным списком как те же UUID в том же порядке, в нижнем регистре; «Валидация чата» — member_ids не массив → 400.

Impact

  • Код:
    • src/utils/cursor.py — разбор курсора;
    • src/api/schemas/common.py — общий тип UUID входа;
    • src/api/schemas/chat.py — member_ids;
    • src/api/routers/v1/chat.py, message.py — chat_id;
    • src/utils/constants.py — шаблон записи UUID.
  • Тесты: student-tests/test_pagination.py, test_chats.py, test_api_conventions.py, при необходимости хелперы api_client.py.
  • Без изменений:
    • схема БД, миграции, сервисы и repo;
    • HAProxy, compose, стенд bench/, проверки отказов;
    • формат курсора: сервер выдаёт тот же, и уже выданные курсоры продолжают работать.
  • Совместимость при поочерёдной замене. Старая и новая реплики выдают одинаковые курсоры. Старая принимает нестрогие UUID, новая — нет. Других различий нет.
  • Стенд. Новый код доходит до реплик через make rolling_update; проверки — make test_isolated и make student_test через LB.