test: cover tampered cursors and UUID input forms
Add black-box tests for the strict-id-validation change: a server-issued cursor with one field changed (non-string or non-canonical item id, v=true, extra field) on both lists, member_ids with values of other JSON types, a non-array member_ids and other UUID notations, and chat_id in the path of the three chat endpoints. Sync the change's delta specs into api-conventions, chats and pagination so the coverage check knows the new scenarios. The cursor and UUID-notation tests fail on the current code by design; the fix follows in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-16
|
||||
@@ -0,0 +1,237 @@
|
||||
# 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` контракта; ответы не меняются.
|
||||
- Курсор принимается только таким, каким его выдал сервер. Формат
|
||||
выдачи прежний: курсоры от реплик до замены работают и после неё.
|
||||
- Каждый новый сценарий спека — тест 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`):
|
||||
|
||||
```python
|
||||
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` после разбора собирает курсор заново из разобранных
|
||||
значений и сравнивает с полученной строкой:
|
||||
|
||||
1. base64url и JSON → объект; `s == scope` (как сейчас);
|
||||
2. `t` и `i` — строки (`isinstance(..., str)`), иначе `CursorError`.
|
||||
Тогда `from_rfc3339` и `UUID` бросают только `ValueError`, и
|
||||
`except` сужается до него;
|
||||
3. `encode_cursor(scope=…, created_at=…, item_id=…) == cursor`, иначе
|
||||
`CursorError("malformed cursor")`.
|
||||
|
||||
Шаг 3 одной проверкой ловит всё, чего сервер не выдаёт:
|
||||
|
||||
- `"v": true` или `1.0` (`True == 1` проходит проверку версии);
|
||||
- `"i"` без дефисов, в верхнем регистре, с `urn:uuid:`;
|
||||
- `"t"` с другим числом знаков дробной части или однозначным месяцем
|
||||
(`strptime` нестрог);
|
||||
- лишние поля, другой порядок ключей, пробелы в JSON, padding `=`.
|
||||
|
||||
Проверка версии (`v != 1` → «unsupported cursor version») остаётся
|
||||
отдельной: у неё своё сообщение и смысл на будущее.
|
||||
|
||||
Стоимость — одна сериализация JSON и base64 на запрос страницы с
|
||||
курсором, единицы микросекунд.
|
||||
|
||||
| Вариант | Почему не он |
|
||||
|---|---|
|
||||
| Добавить `AttributeError` в `except` | правка в одно слово, но ловит слишком широко (может скрыть настоящий дефект) и не трогает `v: true` и другие записи — курсор остаётся «разбирается, значит годен» |
|
||||
| Только проверки типов | убирает 500, но подменённый курсор в другой записи по-прежнему даёт страницу — расходится с «изменённый курсор → 400» |
|
||||
| Проверка каждого поля по отдельности (`type(v) is int`, шаблон для `i`, точная длина `t`) | несколько правил там, где хватает одного инварианта, и легко забыть следующее поле |
|
||||
|
||||
### 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}` останавливается на версии).
|
||||
- **Варианты:** `"i"` = `[]`, `{}`, `123`, `false` (сейчас 500), тот же
|
||||
id без дефисов и в верхнем регистре, `"v": true`, лишнее поле
|
||||
(сейчас 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`.
|
||||
- **[Окно поочерёдной замены]** → старая реплика ещё принимает
|
||||
нестрогую запись, новая — уже нет. Курсоры одинаковы, данные те же.
|
||||
Окно — секунды, и такого ввода никто не шлёт.
|
||||
- **[Тест курсора знает его внутренний формат]** → если формат
|
||||
изменится, упадёт контрольное утверждение хелпера, и тест покраснеет,
|
||||
а не пройдёт молча. Формат меняют вместе с тестом.
|
||||
- **[Будущая версия курсора]** → обратная сборка сравнивает с текущим
|
||||
`encode_cursor`. Новая версия меняет обе функции и тест вместе.
|
||||
- **[Текст ошибки]** → 400 содержит место и сообщение pydantic (`path.chat_id: Value error, must be a UUID in 8-4-4-4-12 form`) без
|
||||
входного значения — как у остальных ошибок валидации (`errors.py`).
|
||||
@@ -0,0 +1,95 @@
|
||||
# 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
|
||||
|
||||
- **Курсор принимается только в записи, которую выдал сервер.**
|
||||
- Значения не того типа больше не роняют разбор.
|
||||
- Подмена любого поля — `"i"`, `"t"`, `"v"`, лишнее поле, другая
|
||||
запись UUID или времени — даёт 400 `invalid_request`, а не 500 и не
|
||||
200.
|
||||
- **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.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: UUID на входе
|
||||
|
||||
Идентификатор, который передаёт клиент, — `chat_id` в пути и элементы
|
||||
`member_ids` в теле — SHALL приниматься только как строка UUID в записи
|
||||
8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), как `format: uuid`
|
||||
контракта. Шестнадцатеричные цифры SHALL приниматься в любом регистре:
|
||||
UUID в верхнем регистре обозначает тот же идентификатор, что в нижнем.
|
||||
В ответах идентификаторы остаются в нижнем регистре (требование
|
||||
«Представление времени и идентификаторов»).
|
||||
|
||||
Значение другого типа (массив, объект, число, логическое значение, null)
|
||||
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
|
||||
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
|
||||
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
|
||||
|
||||
#### Scenario: UUID другого типа в теле
|
||||
|
||||
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
|
||||
элемент — `[]`, `{}`, `123` или `false`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
|
||||
списке чатов Алисы
|
||||
|
||||
#### Scenario: Не UUID в пути
|
||||
|
||||
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
|
||||
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
|
||||
в пути равен `123`, `false`, `[]` или `{}`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`
|
||||
|
||||
#### Scenario: Другая запись UUID
|
||||
|
||||
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
|
||||
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
|
||||
или в фигурных скобках
|
||||
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
|
||||
не создано
|
||||
|
||||
#### Scenario: UUID в верхнем регистре в пути
|
||||
|
||||
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
|
||||
него сообщение, записав `chat_id` в верхнем регистре
|
||||
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
|
||||
`id` и `chat_id` в них — в нижнем регистре
|
||||
@@ -0,0 +1,68 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Создание чата
|
||||
|
||||
`POST /api/v1/chats` SHALL принимать тело
|
||||
`{"title": ..., "member_ids": [...]}` и при успехе отвечать 201 с
|
||||
объектом `Chat`: `id`, `title`, `member_ids`, `created_at`, без других
|
||||
полей. `member_ids` в ответе SHALL совпадать с переданным списком,
|
||||
включая порядок: те же UUID в том же порядке, записанные в нижнем
|
||||
регистре, даже если клиент передал их в верхнем (требования `api-conventions`
|
||||
«UUID на входе» и «Представление времени и идентификаторов»). Чат SHALL
|
||||
создаваться атомарно: при любой ошибке валидации он MUST NOT появиться
|
||||
ни в одном списке.
|
||||
|
||||
#### Scenario: Успешное создание
|
||||
|
||||
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб]
|
||||
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб], `id` — новый UUID
|
||||
|
||||
#### Scenario: Участник в верхнем регистре
|
||||
|
||||
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб], где id Боба
|
||||
записан в верхнем регистре
|
||||
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб] в нижнем регистре,
|
||||
и Боб видит чат в своём списке
|
||||
|
||||
### Requirement: Валидация чата
|
||||
|
||||
`title` SHALL содержать 1–100 Unicode code points и MUST NOT состоять
|
||||
только из пробельных символов. `member_ids` SHALL быть массивом от 1 до
|
||||
100 UUID без повторов; повтором SHALL считаться тот же UUID в любой
|
||||
допустимой записи. Каждый элемент MUST быть идентификатором
|
||||
существующего пользователя, и текущий пользователь MUST входить в
|
||||
список. Нарушение любого условия SHALL давать 400 `invalid_request`.
|
||||
|
||||
#### Scenario: Вызывающего нет в списке
|
||||
|
||||
- **WHEN** Алиса создаёт чат с `member_ids` = [Боб]
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Повтор участника
|
||||
|
||||
- **WHEN** `member_ids` = [Алиса, Алиса]
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Повтор участника в другом регистре
|
||||
|
||||
- **WHEN** `member_ids` = [Алиса, Алиса], где второй id записан в
|
||||
верхнем регистре
|
||||
- **THEN** ответ 400, чат не создан
|
||||
|
||||
#### Scenario: Неизвестный участник
|
||||
|
||||
- **WHEN** `member_ids` содержит UUID, которого нет среди пользователей
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Пустой список
|
||||
|
||||
- **WHEN** `member_ids` = []
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: member_ids не массив
|
||||
|
||||
- **WHEN** `member_ids` равен `{}`, `123`, `false` или строке с id Алисы
|
||||
вместо массива
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, чат не создан
|
||||
@@ -0,0 +1,36 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Курсор непрозрачен и привязан к списку
|
||||
|
||||
Курсор SHALL быть непрозрачной для клиента строкой. Курсор, полученный
|
||||
для другого чата, для списка чатов вместо истории или наоборот, либо
|
||||
повреждённая строка SHALL давать 400 `invalid_request`.
|
||||
|
||||
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
|
||||
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
||||
если он по-прежнему разбирается: ключ элемента другого типа или в другой
|
||||
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
|
||||
страницу списка.
|
||||
|
||||
#### Scenario: Курсор другого чата
|
||||
|
||||
- **WHEN** участник двух чатов передаёт в историю чата B курсор,
|
||||
полученный в чате A
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Повреждённый курсор
|
||||
|
||||
- **WHEN** `cursor` равен произвольной строке `garbage`
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Изменённый курсор
|
||||
|
||||
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
||||
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
||||
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
||||
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
|
||||
кодирует обратно и передаёт в тот же список
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
||||
раскодированный и закодированный обратно без изменений, даёт 200
|
||||
@@ -0,0 +1,193 @@
|
||||
# Tasks
|
||||
|
||||
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
|
||||
дельты `specs/api-conventions`, `specs/pagination`, `specs/chats`.
|
||||
|
||||
**Правила.**
|
||||
|
||||
- **Правила слоёв.** Перед первым файлом слоя — Read его правила и
|
||||
одного файла из каталога, чтобы правило подгрузилось:
|
||||
|
||||
| Что правим | Правила |
|
||||
|---|---|
|
||||
| `student-tests/` | `student-tests.md`, `api-contract.md` |
|
||||
| `src/api/schemas/` | `dto.md`, `api-contract.md` |
|
||||
| `src/api/routers/` | `api-layer.md`, `api-contract.md` |
|
||||
| `src/utils/` | `api-contract.md` (пагинация), `service-layer.md` (курсор) |
|
||||
|
||||
- **Только Edit и Write.** Файлы меняются только ими. Перед правкой —
|
||||
Read файла. Для проверок `uv run python -c …` запускать можно.
|
||||
- **Коммиты — только после подтверждения пользователя:** показать
|
||||
изменения, предложить сообщение (английский, conventional style,
|
||||
последняя строка `Co-Authored-By: Claude Opus 5.5
|
||||
<noreply@anthropic.com>`), ждать ок. Push, checkout, reset, stash —
|
||||
нельзя.
|
||||
- **Упавший тест или прогон** — сначала разбор и названная причина,
|
||||
потом правка (AGENTS.md). Тест не ослабляется под ответ.
|
||||
- **Прогоны по одному.** `make test_isolated` и `make failure_checks` не
|
||||
запускать параллельно друг с другом и с другой сессией
|
||||
(`student-tests.md`).
|
||||
|
||||
## 1. Подготовка
|
||||
|
||||
- [x] 1.1 Прочитать правила из таблицы и по одному файлу каждого слоя:
|
||||
`student-tests/test_pagination.py`, `src/api/schemas/common.py`,
|
||||
`src/api/routers/v1/chat.py`, `src/utils/cursor.py`. Проверка: правила
|
||||
слоёв подгрузились.
|
||||
- [x] 1.2 `openspec validate strict-id-validation --strict` — без
|
||||
ошибок.
|
||||
|
||||
## 2. Тесты на текущем коде (решения 4 и 5)
|
||||
|
||||
- [x] 2.1 `test_pagination.py`, сценарий `pagination` «Изменённый
|
||||
курсор»:
|
||||
- хелпер подмены одного поля выданного курсора; кодирует так же, как
|
||||
сервер (компактный JSON, base64url без `=`);
|
||||
- в хелпере — утверждение, что без изменений он возвращает ту же
|
||||
строку;
|
||||
- фикстура на оба списка: история (два сообщения, `limit=1`) и список
|
||||
чатов (два чата, `limit=1`);
|
||||
- варианты:
|
||||
- `"i"` = `[]`, `{}`, `123`, `false`;
|
||||
- тот же id без дефисов и в верхнем регистре;
|
||||
- `"v": true`;
|
||||
- лишнее поле;
|
||||
- контроль: перекодированный без изменений курсор даёт 200.
|
||||
|
||||
Проверка: `uv run pytest student-tests/test_pagination.py --collect-only
|
||||
-q` показывает тест для обоих списков.
|
||||
- [x] 2.2 `test_chats.py`, сценарии `chats`:
|
||||
- «Участник в верхнем регистре» — 201, `member_ids` в нижнем регистре
|
||||
равен `[alice.id, bob.id]`, Боб видит чат;
|
||||
- «Повтор участника в другом регистре» — 400, чат не создан;
|
||||
- «member_ids не массив» — `{}`, `123`, `false`, строка с id Алисы →
|
||||
400, чат не создан (`listed_titles`).
|
||||
|
||||
Проверка: тесты собираются, маркеры дословно совпадают со сценариями
|
||||
дельты.
|
||||
- [x] 2.3 `test_api_conventions.py`, сценарии `api-conventions`:
|
||||
- «UUID другого типа в теле» — `member_ids` = `[alice.id, X]`, где X —
|
||||
`[]`, `{}`, `123`, `false`; 400, чат не создан;
|
||||
- «Не UUID в пути» — `chat_id` = `123`, `false`, `[]`, `{}` (через
|
||||
`urllib.parse.quote(…, safe="")`) у `GET` чата, `GET` истории и
|
||||
`POST` сообщения с ключом; 400;
|
||||
- «Другая запись UUID»:
|
||||
- id своего чата без дефисов, с `urn:uuid:` и в `{…}` на тех же
|
||||
трёх ручках — 400, история не изменилась;
|
||||
- id Боба в тех же записях в `member_ids` — 400, чат не создан;
|
||||
- «UUID в верхнем регистре в пути» — ответы трёх ручек равны ответам
|
||||
на нижний регистр, `id` и `chat_id` в нижнем регистре.
|
||||
|
||||
Проверка: тесты собираются.
|
||||
- [x] 2.4 Синхронизировать дельты в основные спеки (`/opsx:sync`):
|
||||
сверка покрытия читает только `openspec/specs/`, и без этого маркеры
|
||||
новых сценариев — ссылка на неизвестный сценарий. Проверка:
|
||||
- `openspec validate --specs` без ошибок;
|
||||
- в основных спеках есть новые сценарии.
|
||||
- [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков
|
||||
(после подтверждения; сообщение вроде `test: cover tampered cursors
|
||||
and UUID input forms`). Проверка: `git status` чист.
|
||||
- [ ] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание
|
||||
(решение 5):
|
||||
- красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того
|
||||
типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201);
|
||||
- зелёные — все остальные новые тесты и `test_coverage.py`.
|
||||
|
||||
Расхождение с ожиданием — разбор (AGENTS.md). Если красный тест
|
||||
типов — это дефект, чинить в разделе 3. Вывод с commit, числом тестов
|
||||
и причинами падений — в журнал этапа для 5.1.
|
||||
|
||||
## 3. Исправление (решения 1–2)
|
||||
|
||||
- [ ] 3.1 `UUID_PATTERN` (8-4-4-4-12, шестнадцатеричные цифры в любом
|
||||
регистре) в `src/utils/constants.py`. В `src/api/schemas/common.py` —
|
||||
тип UUID входа: `Annotated[UUID, BeforeValidator(...)]` с
|
||||
`re.fullmatch`; не-строку пропускает дальше. Проверка: `uv run python
|
||||
-c` с `TypeAdapter`:
|
||||
- канон в обоих регистрах принимается;
|
||||
- запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце,
|
||||
`[]`, `{}`, `123`, `false`, `null` — ошибка валидации.
|
||||
- [ ] 3.2 Тип UUID входа у `member_ids` (`src/api/schemas/chat.py`) и у
|
||||
`chat_id` трёх ручек (`src/api/routers/v1/chat.py`, `message.py`).
|
||||
Модели ответов не меняются. Проверка: `make run_dev`, в
|
||||
`/openapi.json` у `chat_id` по-прежнему `{"type": "string",
|
||||
"format": "uuid"}`.
|
||||
- [ ] 3.3 `decode_cursor` (`src/utils/cursor.py`):
|
||||
- `t` и `i` — строки;
|
||||
- `except` только `ValueError`;
|
||||
- обратная сборка через `encode_cursor` и сравнение со входом;
|
||||
- докстринг модуля и функции — под новое правило.
|
||||
|
||||
Проверка: `uv run python -c` — на всех вариантах 2.1 и на
|
||||
`garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого
|
||||
исключения нет; на выданном курсоре — тот же ключ.
|
||||
- [ ] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста
|
||||
реплик пропущены с причиной «one API process». Вывод — в журнал
|
||||
этапа.
|
||||
- [ ] 3.5 Правило `.claude/rules/api-contract.md`:
|
||||
- «Валидация → 400»: pydantic принимает UUID шире `format: uuid`;
|
||||
вход с UUID (путь и тело) — только через тип UUID входа из
|
||||
`common.py`, ответы — `UUID`;
|
||||
- «Пагинация (keyset)»: курсор принимается только в записи сервера
|
||||
(обратная сборка).
|
||||
|
||||
Проверка: названные в правиле файлы и тип существуют.
|
||||
- [ ] 3.6 Commit исправления и правила (после подтверждения; сообщение
|
||||
вроде `fix: reject tampered cursors and non-canonical UUIDs`).
|
||||
Проверка: `git status` чист.
|
||||
|
||||
## 4. Стенд и регрессия (решение 6)
|
||||
|
||||
- [ ] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
|
||||
`make lb_stats` — оба слота `UP` на новом образе, `make instances` —
|
||||
`instances: 2`.
|
||||
- [ ] 4.2 `make test` и `make student_test` через LB. Проверка:
|
||||
- `PASS` и все тесты прошли, включая тесты реплик;
|
||||
- в журнале реплик за время прогона нет ответов 500 (`make logs`,
|
||||
access-лог, поле статуса).
|
||||
- [ ] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
|
||||
сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов
|
||||
удалён.
|
||||
- [ ] 4.4 Чистый clone во временном проекте compose на нестандартных
|
||||
портах, по процедуре `evidence/replicas/clean-clone-ports.md`:
|
||||
`git clone` commit 3.6, `make run_docker`, `make test`, `make
|
||||
student_test` через LB клона, затем `down -v` клона. Проверка:
|
||||
всё код 0, рабочий стенд `mtusi-lab3` не тронут.
|
||||
- [ ] 4.5 Спросить пользователя о полной проверке из чистого clone на
|
||||
портах по умолчанию (`evidence/tests/clean-clone-final.md`): она
|
||||
удаляет рабочий стенд с volume. Без согласия — не делать и записать
|
||||
в 5.1, что не делалась.
|
||||
|
||||
## 5. Документы
|
||||
|
||||
- [ ] 5.1 `evidence/tests/strict-id-validation-checks.md`:
|
||||
- красный прогон 2.6 и зелёный 3.4 — commit, число тестов, причины
|
||||
падений;
|
||||
- 4.1–4.4 и решение по 4.5.
|
||||
|
||||
Только обезличенные выводы, без токенов и паролей
|
||||
(`evidence/README.md`).
|
||||
- [ ] 5.2 `REPORT.md`:
|
||||
- строка в таблице доказательств: строгий вход с UUID и курсор, red →
|
||||
green, ссылка на 5.1;
|
||||
- расхождение с прежним поведением: запись UUID без дефисов,
|
||||
`urn:uuid:` и `{…}` → 400;
|
||||
- число тестов там, где отчёт говорит о текущем коде.
|
||||
|
||||
Проверка: Read раздела после правки; числа совпадают с 4.2 и 3.4.
|
||||
- [ ] 5.3 `AGENTS.md`:
|
||||
- абзац о состоянии лабы: change `strict-id-validation`;
|
||||
- карта кода: тип UUID входа в `common.py`, обратная сборка в
|
||||
`cursor.py`.
|
||||
|
||||
Проверка: Read абзаца и карты.
|
||||
- [ ] 5.4 `graphify update .` — граф собран без ошибок.
|
||||
- [ ] 5.5 Commit документов (после подтверждения; сообщение вроде `docs:
|
||||
record strict-id-validation checks`). Проверка: `git status` чист.
|
||||
|
||||
## 6. Завершение
|
||||
|
||||
- [ ] 6.1 `/opsx:verify strict-id-validation`. Найденное исправить
|
||||
новым commit с повтором затронутых проверок.
|
||||
- [ ] 6.2 `/opsx:archive strict-id-validation` после ок пользователя.
|
||||
Проверка: change в `openspec/changes/archive/`, активных changes нет.
|
||||
@@ -183,3 +183,47 @@ Unicode code points.
|
||||
|
||||
- **WHEN** клиент получает любой объект с `id`
|
||||
- **THEN** значение — UUID в нижнем регистре
|
||||
|
||||
### Requirement: UUID на входе
|
||||
|
||||
Идентификатор, который передаёт клиент, — `chat_id` в пути и элементы
|
||||
`member_ids` в теле — SHALL приниматься только как строка UUID в записи
|
||||
8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), как `format: uuid`
|
||||
контракта. Шестнадцатеричные цифры SHALL приниматься в любом регистре:
|
||||
UUID в верхнем регистре обозначает тот же идентификатор, что в нижнем.
|
||||
В ответах идентификаторы остаются в нижнем регистре (требование
|
||||
«Представление времени и идентификаторов»).
|
||||
|
||||
Значение другого типа (массив, объект, число, логическое значение, null)
|
||||
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
|
||||
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
|
||||
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
|
||||
|
||||
#### Scenario: UUID другого типа в теле
|
||||
|
||||
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
|
||||
элемент — `[]`, `{}`, `123` или `false`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
|
||||
списке чатов Алисы
|
||||
|
||||
#### Scenario: Не UUID в пути
|
||||
|
||||
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
|
||||
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
|
||||
в пути равен `123`, `false`, `[]` или `{}`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`
|
||||
|
||||
#### Scenario: Другая запись UUID
|
||||
|
||||
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
|
||||
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
|
||||
или в фигурных скобках
|
||||
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
|
||||
не создано
|
||||
|
||||
#### Scenario: UUID в верхнем регистре в пути
|
||||
|
||||
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
|
||||
него сообщение, записав `chat_id` в верхнем регистре
|
||||
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
|
||||
`id` и `chat_id` в них — в нижнем регистре
|
||||
|
||||
@@ -14,21 +14,32 @@
|
||||
`{"title": ..., "member_ids": [...]}` и при успехе отвечать 201 с
|
||||
объектом `Chat`: `id`, `title`, `member_ids`, `created_at`, без других
|
||||
полей. `member_ids` в ответе SHALL совпадать с переданным списком,
|
||||
включая порядок. Чат SHALL создаваться атомарно: при любой ошибке
|
||||
валидации он MUST NOT появиться ни в одном списке.
|
||||
включая порядок: те же UUID в том же порядке, записанные в нижнем
|
||||
регистре, даже если клиент передал их в верхнем (требования `api-conventions`
|
||||
«UUID на входе» и «Представление времени и идентификаторов»). Чат SHALL
|
||||
создаваться атомарно: при любой ошибке валидации он MUST NOT появиться
|
||||
ни в одном списке.
|
||||
|
||||
#### Scenario: Успешное создание
|
||||
|
||||
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб]
|
||||
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб], `id` — новый UUID
|
||||
|
||||
#### Scenario: Участник в верхнем регистре
|
||||
|
||||
- **WHEN** Алиса создаёт чат с `member_ids` = [Алиса, Боб], где id Боба
|
||||
записан в верхнем регистре
|
||||
- **THEN** ответ 201, `member_ids` равен [Алиса, Боб] в нижнем регистре,
|
||||
и Боб видит чат в своём списке
|
||||
|
||||
### Requirement: Валидация чата
|
||||
|
||||
`title` SHALL содержать 1–100 Unicode code points и MUST NOT состоять
|
||||
только из пробельных символов. `member_ids` SHALL содержать от 1 до 100
|
||||
UUID без повторов; каждый MUST быть идентификатором существующего
|
||||
пользователя, и текущий пользователь MUST входить в список. Нарушение
|
||||
любого условия SHALL давать 400 `invalid_request`.
|
||||
только из пробельных символов. `member_ids` SHALL быть массивом от 1 до
|
||||
100 UUID без повторов; повтором SHALL считаться тот же UUID в любой
|
||||
допустимой записи. Каждый элемент MUST быть идентификатором
|
||||
существующего пользователя, и текущий пользователь MUST входить в
|
||||
список. Нарушение любого условия SHALL давать 400 `invalid_request`.
|
||||
|
||||
#### Scenario: Вызывающего нет в списке
|
||||
|
||||
@@ -40,6 +51,12 @@ UUID без повторов; каждый MUST быть идентификат
|
||||
- **WHEN** `member_ids` = [Алиса, Алиса]
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Повтор участника в другом регистре
|
||||
|
||||
- **WHEN** `member_ids` = [Алиса, Алиса], где второй id записан в
|
||||
верхнем регистре
|
||||
- **THEN** ответ 400, чат не создан
|
||||
|
||||
#### Scenario: Неизвестный участник
|
||||
|
||||
- **WHEN** `member_ids` содержит UUID, которого нет среди пользователей
|
||||
@@ -50,6 +67,12 @@ UUID без повторов; каждый MUST быть идентификат
|
||||
- **WHEN** `member_ids` = []
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: member_ids не массив
|
||||
|
||||
- **WHEN** `member_ids` равен `{}`, `123`, `false` или строке с id Алисы
|
||||
вместо массива
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, чат не создан
|
||||
|
||||
### Requirement: Получение чата
|
||||
|
||||
`GET /api/v1/chats/{chat_id}` SHALL отвечать 200 с объектом `Chat`,
|
||||
|
||||
@@ -62,6 +62,12 @@
|
||||
для другого чата, для списка чатов вместо истории или наоборот, либо
|
||||
повреждённая строка SHALL давать 400 `invalid_request`.
|
||||
|
||||
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
|
||||
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
||||
если он по-прежнему разбирается: ключ элемента другого типа или в другой
|
||||
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
|
||||
страницу списка.
|
||||
|
||||
#### Scenario: Курсор другого чата
|
||||
|
||||
- **WHEN** участник двух чатов передаёт в историю чата B курсор,
|
||||
@@ -72,3 +78,13 @@
|
||||
|
||||
- **WHEN** `cursor` равен произвольной строке `garbage`
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Изменённый курсор
|
||||
|
||||
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
||||
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
||||
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
||||
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
|
||||
кодирует обратно и передаёт в тот же список
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
||||
раскодированный и закодированный обратно без изменений, даёт 200
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable
|
||||
from collections.abc import Iterable, Mapping
|
||||
from datetime import datetime, timedelta
|
||||
from functools import cache
|
||||
from pathlib import Path
|
||||
@@ -143,6 +143,23 @@ def assert_error(resp: httpx.Response, status: int) -> dict[str, Any]:
|
||||
return error
|
||||
|
||||
|
||||
def assert_errors(
|
||||
responses: Mapping[str, httpx.Response],
|
||||
status: int,
|
||||
) -> None:
|
||||
"""Каждый вариант запроса — ошибка `status` в формате контракта.
|
||||
|
||||
Статусы сверяются все разом: при падении видно, что ответил каждый
|
||||
вариант, а не только первый.
|
||||
"""
|
||||
statuses = {name: resp.status_code for name, resp in responses.items()}
|
||||
assert set(statuses.values()) == {status}, (
|
||||
f"expected {status} for every variant, got {statuses}"
|
||||
)
|
||||
for resp in responses.values():
|
||||
assert_error(resp, status)
|
||||
|
||||
|
||||
def assert_unauthorized(
|
||||
resp: httpx.Response,
|
||||
challenge: str,
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
форматы."""
|
||||
|
||||
import json
|
||||
import urllib.parse
|
||||
import uuid
|
||||
from collections import Counter
|
||||
from typing import Any
|
||||
|
||||
@@ -19,6 +21,7 @@ from api_client import (
|
||||
from contract import (
|
||||
assert_created_at,
|
||||
assert_error,
|
||||
assert_errors,
|
||||
assert_instance_id,
|
||||
assert_ok,
|
||||
assert_uuid,
|
||||
@@ -26,6 +29,10 @@ from contract import (
|
||||
)
|
||||
|
||||
UNICODE_TEXT = "Привет, мир 👋"
|
||||
# не UUID в пути: типы JSON, записанные строкой URL
|
||||
NOT_UUID_PATHS = ("123", "false", "[]", "{}")
|
||||
# не UUID в элементе member_ids: значения других типов JSON
|
||||
NOT_UUID_VALUES: tuple[Any, ...] = ([], {}, 123, False)
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "Unicode сохраняется")
|
||||
@@ -259,3 +266,126 @@ def test_id_and_created_at_format(
|
||||
assert_uuid(member_id)
|
||||
assert_uuid(message["chat_id"])
|
||||
assert_uuid(message["sender_id"])
|
||||
|
||||
|
||||
def other_uuid_forms(value: str) -> dict[str, str]:
|
||||
"""Тот же UUID в записях, которых нет в `format: uuid` контракта."""
|
||||
return {
|
||||
"no hyphens": value.replace("-", ""),
|
||||
"urn": f"urn:uuid:{value}",
|
||||
"braces": f"{{{value}}}",
|
||||
}
|
||||
|
||||
|
||||
def chat_id_requests(
|
||||
api: Api,
|
||||
actor: Actor,
|
||||
chat_id: str,
|
||||
) -> dict[str, httpx.Response]:
|
||||
"""Три ручки с `chat_id` в пути; значение кодируется для URL явно."""
|
||||
quoted = urllib.parse.quote(chat_id, safe="")
|
||||
return {
|
||||
"GET chat": api.request("GET", f"{API}/chats/{quoted}", actor=actor),
|
||||
"GET history": api.messages_page(actor, quoted),
|
||||
"POST message": api.post_message(
|
||||
actor,
|
||||
quoted,
|
||||
json={"text": "path"},
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def post_chat(
|
||||
api: Api,
|
||||
actor: Actor,
|
||||
title: str,
|
||||
member_ids: list[Any],
|
||||
) -> httpx.Response:
|
||||
return api.request(
|
||||
"POST",
|
||||
f"{API}/chats",
|
||||
actor=actor,
|
||||
json={"title": title, "member_ids": member_ids},
|
||||
)
|
||||
|
||||
|
||||
def chat_titles(api: Api, actor: Actor) -> set[str]:
|
||||
return {
|
||||
chat["title"]
|
||||
for page in api.chat_pages(actor)
|
||||
for chat in page["items"]
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "UUID другого типа в теле")
|
||||
def test_uuid_of_other_type_in_body(api: Api, alice: Actor) -> None:
|
||||
title = f"rejected-{uuid.uuid4().hex}"
|
||||
# рядом с id Алисы: иначе 400 дала бы и проверка «вызывающий в списке»
|
||||
assert_errors(
|
||||
{
|
||||
repr(value): post_chat(api, alice, title, [alice.id, value])
|
||||
for value in NOT_UUID_VALUES
|
||||
},
|
||||
400,
|
||||
)
|
||||
assert title not in chat_titles(api, alice)
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "Не UUID в пути")
|
||||
def test_not_uuid_in_path(api: Api, alice: Actor) -> None:
|
||||
assert_errors(
|
||||
{
|
||||
f"{name} {value}": resp
|
||||
for value in NOT_UUID_PATHS
|
||||
for name, resp in chat_id_requests(api, alice, value).items()
|
||||
},
|
||||
400,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "Другая запись UUID")
|
||||
def test_other_uuid_forms(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
bob: Actor,
|
||||
chat: dict[str, Any],
|
||||
) -> None:
|
||||
history = api.all_messages(alice, chat["id"])
|
||||
title = f"rejected-{uuid.uuid4().hex}"
|
||||
responses = {
|
||||
f"{name} / {form}": resp
|
||||
for form, value in other_uuid_forms(chat["id"]).items()
|
||||
for name, resp in chat_id_requests(api, alice, value).items()
|
||||
}
|
||||
responses |= {
|
||||
f"member_ids / {form}": post_chat(api, alice, title, [alice.id, value])
|
||||
for form, value in other_uuid_forms(bob.id).items()
|
||||
}
|
||||
assert_errors(responses, 400)
|
||||
assert api.all_messages(alice, chat["id"]) == history
|
||||
assert title not in chat_titles(api, alice)
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "UUID в верхнем регистре в пути")
|
||||
def test_upper_case_uuid_in_path(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
chat: dict[str, Any],
|
||||
) -> None:
|
||||
upper = chat["id"].upper()
|
||||
got = api.request("GET", f"{API}/chats/{upper}", actor=alice)
|
||||
# assert_ok проверяет и формат: id и chat_id в ответах — нижний регистр
|
||||
assert assert_ok(got, 200, "Chat") == chat
|
||||
sent = assert_ok(
|
||||
api.post_message(alice, upper, json={"text": "upper"}),
|
||||
201,
|
||||
"Message",
|
||||
)
|
||||
assert sent["chat_id"] == chat["id"]
|
||||
upper_page = assert_ok(api.messages_page(alice, upper), 200, "MessagePage")
|
||||
lower_page = assert_ok(
|
||||
api.messages_page(alice, chat["id"]),
|
||||
200,
|
||||
"MessagePage",
|
||||
)
|
||||
assert upper_page == lower_page == {"items": [sent], "next_cursor": None}
|
||||
|
||||
@@ -7,14 +7,14 @@ import httpx
|
||||
import pytest
|
||||
|
||||
from api_client import API, Actor, Api
|
||||
from contract import assert_error, assert_ok
|
||||
from contract import assert_error, assert_errors, assert_ok
|
||||
|
||||
|
||||
def create_raw(
|
||||
api: Api,
|
||||
actor: Actor,
|
||||
title: str,
|
||||
member_ids: list[str],
|
||||
member_ids: Any,
|
||||
) -> httpx.Response:
|
||||
return api.request(
|
||||
"POST",
|
||||
@@ -78,6 +78,35 @@ def test_empty_members(api: Api, alice: Actor) -> None:
|
||||
assert_error(create_raw(api, alice, "Empty", []), 400)
|
||||
|
||||
|
||||
@pytest.mark.spec("chats", "Участник в верхнем регистре")
|
||||
def test_member_in_upper_case(api: Api, alice: Actor, bob: Actor) -> None:
|
||||
resp = create_raw(api, alice, "Upper", [alice.id, bob.id.upper()])
|
||||
chat = assert_ok(resp, 201, "Chat")
|
||||
assert chat["member_ids"] == [alice.id, bob.id]
|
||||
assert chat["id"] in listed_ids(api, bob)
|
||||
|
||||
|
||||
@pytest.mark.spec("chats", "Повтор участника в другом регистре")
|
||||
def test_duplicate_member_other_case(api: Api, alice: Actor) -> None:
|
||||
title = f"rejected-{uuid.uuid4().hex}"
|
||||
member_ids = [alice.id, alice.id.upper()]
|
||||
assert_error(create_raw(api, alice, title, member_ids), 400)
|
||||
assert title not in listed_titles(api, alice)
|
||||
|
||||
|
||||
@pytest.mark.spec("chats", "member_ids не массив")
|
||||
def test_member_ids_not_array(api: Api, alice: Actor) -> None:
|
||||
title = f"rejected-{uuid.uuid4().hex}"
|
||||
assert_errors(
|
||||
{
|
||||
repr(member_ids): create_raw(api, alice, title, member_ids)
|
||||
for member_ids in ({}, 123, False, alice.id)
|
||||
},
|
||||
400,
|
||||
)
|
||||
assert title not in listed_titles(api, alice)
|
||||
|
||||
|
||||
@pytest.mark.spec("chats", "Участник")
|
||||
def test_member_reads_chat(
|
||||
api: Api,
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
"""Спек `pagination`: `limit`, `next_cursor`, курсоры обоих списков."""
|
||||
|
||||
import base64
|
||||
import json
|
||||
from collections.abc import Callable
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
@@ -8,7 +10,23 @@ import httpx
|
||||
import pytest
|
||||
|
||||
from api_client import Actor, Api, order_key
|
||||
from contract import assert_error, assert_ok
|
||||
from contract import assert_error, assert_errors, assert_ok
|
||||
|
||||
# подмена в содержимом курсора: какие поля заменить
|
||||
type Change = Callable[[dict[str, Any]], dict[str, Any]]
|
||||
|
||||
# подмены выданного курсора (сценарий «Изменённый курсор»): ключ элемента
|
||||
# не строка, тот же id в другой записи, версия true, лишнее поле
|
||||
CURSOR_CHANGES: dict[str, Change] = {
|
||||
"i=[]": lambda _: {"i": []},
|
||||
"i={}": lambda _: {"i": {}},
|
||||
"i=123": lambda _: {"i": 123},
|
||||
"i=false": lambda _: {"i": False},
|
||||
"i without hyphens": lambda payload: {"i": payload["i"].replace("-", "")},
|
||||
"i upper case": lambda payload: {"i": payload["i"].upper()},
|
||||
"v=true": lambda _: {"v": True},
|
||||
"extra field": lambda _: {"x": 1},
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -161,3 +179,70 @@ def test_garbage_cursor(listing: Listing) -> None:
|
||||
# eyJ4IjoxfQ — корректный base64 от {"x":1}, но не курсор сервиса
|
||||
for cursor in ("garbage", "eyJ4IjoxfQ", "!!!"):
|
||||
assert_error(listing.page(cursor=cursor), 400)
|
||||
|
||||
|
||||
def cursor_payload(cursor: str) -> dict[str, Any]:
|
||||
"""Содержимое курсора сервиса: base64url без `=` от JSON."""
|
||||
padded = cursor + "=" * (-len(cursor) % 4)
|
||||
return json.loads(base64.urlsafe_b64decode(padded))
|
||||
|
||||
|
||||
def encode_payload(payload: dict[str, Any]) -> str:
|
||||
"""Курсор из содержимого — так же, как его кодирует сервис."""
|
||||
raw = json.dumps(payload, separators=(",", ":")).encode()
|
||||
return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
|
||||
|
||||
|
||||
def tamper(cursor: str, change: Change) -> str:
|
||||
"""Выданный курсор с одной подменой в содержимом.
|
||||
|
||||
Без подмены перекодирование обязано вернуть ту же строку: иначе формат
|
||||
курсора изменился, и 400 на подмену ничего бы не доказывал.
|
||||
"""
|
||||
payload = cursor_payload(cursor)
|
||||
assert encode_payload(payload) == cursor, (
|
||||
f"cursor format changed, re-encoded payload differs: {payload}"
|
||||
)
|
||||
return encode_payload(payload | change(payload))
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class IssuedCursor:
|
||||
"""Список и курсор его второй страницы, выданный сервером."""
|
||||
|
||||
listing: Listing
|
||||
cursor: str
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def issued(
|
||||
listing: Listing,
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
bob: Actor,
|
||||
chat: dict[str, Any],
|
||||
) -> IssuedCursor:
|
||||
"""В истории два сообщения, у Алисы два чата: у обоих списков есть
|
||||
вторая страница при `limit=1`."""
|
||||
fill(api, alice, chat["id"], 2)
|
||||
api.create_chat(alice, bob, title="second")
|
||||
first = assert_ok(listing.page(limit=1), 200, listing.schema)
|
||||
assert first["next_cursor"], "no second page"
|
||||
return IssuedCursor(listing=listing, cursor=first["next_cursor"])
|
||||
|
||||
|
||||
@pytest.mark.spec("pagination", "Изменённый курсор")
|
||||
def test_tampered_cursor(issued: IssuedCursor) -> None:
|
||||
"""Курсор не собирается с нуля: с чужими `v` или `s` его отсекла бы
|
||||
проверка версии или области раньше разбора ключа."""
|
||||
page = issued.listing.page
|
||||
# контроль: тот же курсор, перекодированный без подмены, принимается
|
||||
unchanged = tamper(issued.cursor, lambda _: {})
|
||||
assert_ok(page(cursor=unchanged), 200, issued.listing.schema)
|
||||
assert_errors(
|
||||
{
|
||||
name: page(cursor=tamper(issued.cursor, change))
|
||||
for name, change in CURSOR_CHANGES.items()
|
||||
},
|
||||
400,
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user