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

98 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.