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>
98 lines
6.3 KiB
Markdown
98 lines
6.3 KiB
Markdown
# 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.
|