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:
2026-10-16 12:51:16 +03:00
co-authored by Claude Opus 5.5
parent 40f470f5b4
commit c5d5a1ab25
14 changed files with 1032 additions and 10 deletions
@@ -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 нет.
+44
View File
@@ -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` в них — в нижнем регистре
+29 -6
View File
@@ -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`,
+16
View File
@@ -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
+18 -1
View File
@@ -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,
+130
View File
@@ -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}
+31 -2
View File
@@ -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,
+86 -1
View File
@@ -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,
)