fix: check cursor fields instead of re-encoding

628b5f2 accepted a cursor only if re-encoding the parsed key gave the
same string. That closed the format both ways: any encoding change, even
a compatible one (an optional field, key order, to_rfc3339 shared with
API responses), would turn cursors issued by a replica of the other
version into 400 during make rolling_update, which the tests cannot see.

decode_cursor now checks the fields one by one: v must be exactly the
integer 1, t and i must be strings, i must be in the server's notation
(lowercase 8-4-4-4-12). Unknown fields are ignored, so a tampered cursor
is still a 400 while the format stays open for compatible changes. The
rule records how to change the format: a new CURSOR_VERSION, with both
versions accepted while replicas are replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-16 13:11:57 +03:00
co-authored by Claude Opus 5.5
parent 628b5f2278
commit 8fe467ace0
8 changed files with 170 additions and 76 deletions
+18 -7
View File
@@ -172,13 +172,24 @@ FastAPI 0.141 из `uv.lock`:
или пользователя, битая base64 или JSON → 400. Последний элемент
предыдущей страницы не повторяется. `limit` между страницами можно
менять.
- Курсор принимается только в записи, которую выдал сервер:
`decode_cursor` после разбора собирает его заново (`encode_cursor`) и
сравнивает со входом. Изменённый курсор — `"i"` не строка, тот же id в
другой записи, `"v": true`, лишнее поле — 400, а не 500 и не страница
(спек `pagination`, «Изменённый курсор»). Значения курсора до
`UUID()` и `strptime` проверяются на тип: `UUID()` на не-строке роняет
`AttributeError`, а не `ValueError` (change `strict-id-validation`).
- Изменённый курсор — 400, а не 500 и не страница (спек `pagination`,
«Изменённый курсор»). `decode_cursor` проверяет поля по отдельности
(change `strict-id-validation`):
- `v` — ровно целое 1 (`type(v) is int`: `True == 1`);
- `t` и `i` — строки до `strptime` и `UUID()`: `UUID()` на не-строке
роняет `AttributeError`, а не `ValueError`;
- `i` — в записи сервера, `str(UUID(i)) == i`.
- Незнакомые поля курсора игнорируются, и курсор не сравнивается с
обратной сборкой (`encode_cursor(...) == cursor`): иначе формат закрыт,
и даже совместимая правка (необязательное поле, порядок ключей,
`to_rfc3339`, общий с ответами) давала бы 400 курсорам реплики другой
версии во время `make rolling_update`. Тесты такое окно не ловят:
курсор в них выдаёт и проверяет один код.
- Формат курсора, который прежний код не прочтёт (переименованное поле,
другая запись времени), — новая `CURSOR_VERSION`. На время замены
реплик новая версия принимает и старую `v`: курсор, выданный старой
репликой, приходит на новую. Старую версию убирать отдельной правкой,
когда старых реплик не осталось.
- Семантику при конкурентных вставках и ограничения часов описать в
`REPORT.md` (например: `created_at` монотонен внутри чата).
- В Postgres порядок и курсор задаёт SQL: сравнение кортежей
+58 -27
View File
@@ -48,8 +48,9 @@
- Никакой ввод в `cursor`, `chat_id` и `member_ids` не даёт 500.
- Вход с UUID — ровно `format: uuid` контракта; ответы не меняются.
- Курсор принимается только таким, каким его выдал сервер. Формат
выдачи прежний: курсоры от реплик до замены работают и после неё.
- Подменённый курсор — 400. Формат при этом остаётся открытым для
совместимых правок: незнакомые поля игнорируются. Формат выдачи
прежний: курсоры от реплик до замены работают и после неё.
- Каждый новый сценарий спека — тест black-box. Тесты курсора и записи
UUID красные на текущем коде, это показано в evidence.
@@ -107,37 +108,39 @@ UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)]
сообщения не доходит до сервиса, ключ идемпотентности не занимается
(сценарий `idempotency` «Невалидный запрос не занимает ключ»).
### 2. Курсор — проверка обратной сборкой
### 2. Курсор — проверка полей, незнакомые поля игнорируются
`decode_cursor` после разбора собирает курсор заново из разобранных
значений и сравнивает с полученной строкой:
`decode_cursor` после разбора base64url и JSON проверяет поля по
отдельности:
1. base64url и JSON → объект; `s == scope` (как сейчас);
2. `t` и `i` — строки (`isinstance(..., str)`), иначе `CursorError`.
1. объект; `v` — ровно целое `1`. Тип проверяется отдельно: `bool` —
подкласс `int`, и `True == 1` прошло бы прежнее сравнение;
2. `s == scope` (как сейчас);
3. `t` и `i` — строки (`isinstance(..., str)`), иначе `CursorError`.
Тогда `from_rfc3339` и `UUID` бросают только `ValueError`, и
`except` сужается до него;
3. `encode_cursor(scope=…, created_at=…, item_id=…) == cursor`, иначе
`CursorError("malformed cursor")`.
4. `i` — в записи сервера: `str(UUID(i)) == i` (8-4-4-4-12, нижний
регистр). Запись UUID от версии кода не зависит, так что эта проверка
формат на будущее не закрывает.
Шаг 3 одной проверкой ловит всё, чего сервер не выдаёт:
Принимаются, потому что разбираются в тот же ключ:
- `"v": true` или `1.0` (`True == 1` проходит проверку версии);
- `"i"` без дефисов, в верхнем регистре, с `urn:uuid:`;
- `"t"` с другим числом знаков дробной части или однозначным месяцем
(`strptime` нестрог);
- лишние поля, другой порядок ключей, пробелы в JSON, padding `=`.
- незнакомые поля — игнорируются;
- пробелы и порядок ключей в JSON;
- padding `=`.
Проверка версии (`v != 1` → «unsupported cursor version») остаётся
отдельной: у неё своё сообщение и смысл на будущее.
Стоимость — одна сериализация JSON и base64 на запрос страницы с
курсором, единицы микросекунд.
Формат, который прежний код не прочтёт (переименованное поле, другой
формат времени), — новая версия `v`. На время `make rolling_update`
новая версия принимает обе: курсор, выданный старой репликой, приходит
на новую (правило `api-contract.md`, «Пагинация (keyset)»).
| Вариант | Почему не он |
|---|---|
| Добавить `AttributeError` в `except` | правка в одно слово, но ловит слишком широко (может скрыть настоящий дефект) и не трогает `v: true` и другие записи — курсор остаётся «разбирается, значит годен» |
| Только проверки типов | убирает 500, но подменённый курсор в другой записи по-прежнему даёт страницу — расходится с «изменённый курсор → 400» |
| Проверка каждого поля по отдельности (`type(v) is int`, шаблон для `i`, точная длина `t`) | несколько правил там, где хватает одного инварианта, и легко забыть следующее поле |
| Только проверки типов | убирает 500, но подменённый курсор (`v: true`, id в другой записи) по-прежнему даёт страницу — расходится с «изменённый курсор → 400» |
| Обратная сборка: `encode_cursor(...) == cursor` | первая реализация (`628b5f2`), заменена в apply по просьбе пользователя (раздел «Пересмотр в apply») |
| Отвергать незнакомые поля | тот же закрытый формат: необязательное поле нового кода давало бы 400 на старых репликах во время замены |
| Строгая запись `t`: `to_rfc3339(from_rfc3339(t)) == t` | связывает курсор с форматом времени ответов API (`to_rfc3339` общий). Нестрогая запись времени разбирается в позицию того же списка, вреда нет |
### 3. Без подписи курсора
@@ -150,7 +153,7 @@ HMAC сделал бы подмену невозможной, но:
- **угрозы нет:** область `s` уже привязывает курсор к своему списку.
Подменённый ключ сдвигает позицию только внутри списка, который
пользователь и так вправе читать. Требование — 400 вместо 500 и
вместо страницы, и обратная сборка его выполняет.
вместо страницы, и проверка полей его выполняет.
### 4. Тесты: подмена настоящего курсора и некрасный контроль
@@ -165,9 +168,11 @@ HMAC сделал бы подмену невозможной, но:
отсекается до места дефекта, и тест был бы зелёным без
исправления. Ровно так устроен нынешний `test_garbage_cursor`
(`{"x":1}` останавливается на версии).
- **Варианты:** `"i"` = `[]`, `{}`, `123`, `false` (сейчас 500), тот же
id без дефисов и в верхнем регистре, `"v": true`, лишнее поле
- **Варианты → 400:** `"i"` = `[]`, `{}`, `123`, `false` (сейчас 500),
тот же id без дефисов и в верхнем регистре, `"v": true` и `1.0`
(сейчас 200).
- **Варианты → 200 и та же страница:** без изменений и с лишним полем
(незнакомые поля игнорируются).
- **Оба списка:** история (два сообщения, `limit=1`) и список чатов
(два чата, `limit=1`).
- **`member_ids`** (`test_chats.py`).
@@ -231,7 +236,33 @@ change. Вывод — в `evidence/tests/strict-id-validation-checks.md`
- **[Тест курсора знает его внутренний формат]** → если формат
изменится, упадёт контрольное утверждение хелпера, и тест покраснеет,
а не пройдёт молча. Формат меняют вместе с тестом.
- **[Будущая версия курсора]** → обратная сборка сравнивает с текущим
`encode_cursor`. Новая версия меняет обе функции и тест вместе.
- **[Несовместимая правка формата курсора]** → новая `v`, на время
замены реплик принимаются обе (правило `api-contract.md`). Тесты этого
окна не проверяют: курсор в них выдаёт и проверяет один код.
- **[Текст ошибки]** → 400 содержит место и сообщение pydantic (`path.chat_id: Value error, must be a UUID in 8-4-4-4-12 form`) без
входного значения — как у остальных ошибок валидации (`errors.py`).
## Пересмотр в apply
Первая реализация курсора (`628b5f2`) — обратная сборка: разобранный
курсор собирался заново через `encode_cursor` и сравнивался со входом.
Подсказка бокового агента указала цену этого решения, и пользователь
попросил смягчить:
- **Формат закрыт в обе стороны.** Любая правка кодирования, даже
совместимая, ломает курсоры реплики другой версии. Совместимые правки —
необязательное поле, порядок ключей, `to_rfc3339`: он общий с форматом
времени в ответах.
- **Ломается во время `make rolling_update`.** Клиент листает историю,
следующую страницу отдаёт реплика другой версии, и он получает 400.
Тесты этого не ловят: курсор в них выдаёт и проверяет один код.
- **Выигрыш почти нулевой.** Подменённый, но разбираемый курсор указывает
на позицию в списке, который пользователь и так вправе читать.
Контракт требует только «битый курсор → 400» и «курсор другого чата →
400». Строгость «только запись сервера» в сценарии спека появилась при
propose, рецензент её не просил.
Заменено решением 2: проверка полей, незнакомые поля игнорируются. Из
сценария «Изменённый курсор» убрано «добавляет поле → 400», добавлено
«с добавленным незнакомым полем — 200 и та же страница». В правило — как
менять формат: новая `v`, на время замены принимаются обе.
@@ -26,11 +26,13 @@
## What Changes
- **Курсор принимается только в записи, которую выдал сервер.**
- **Подменённый курсор — 400.**
- Значения не того типа больше не роняют разбор.
- Подмена любого поля — `"i"`, `"t"`, `"v"`, лишнее поле, другая
запись UUID или времени — даёт 400 `invalid_request`, а не 500 и не
200.
- Ключ элемента не строка или не в записи сервера, версия не ровно
целое 1 — 400 `invalid_request`, а не 500 и не 200.
- Незнакомые поля игнорируются: формат остаётся открытым для
совместимых правок, и курсоры не ломаются при поочерёдной замене
реплик (design, «Пересмотр в apply»).
- **UUID на входе — только запись 8-4-4-4-12.** Это `chat_id` в пути трёх
ручек (`GET /chats/{chat_id}`, `GET` и `POST
/chats/{chat_id}/messages`) и элементы `member_ids` в `POST /chats`.
@@ -8,11 +8,12 @@
для другого чата, для списка чатов вместо истории или наоборот, либо
повреждённая строка SHALL давать 400 `invalid_request`.
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
если он по-прежнему разбирается: ключ элемента другого типа или в другой
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
страницу списка.
если он по-прежнему разбирается: ключ элемента другого типа или не в той
записи, в которой его выдал сервер, версия другого значения или типа.
Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых
сервер не знает, SHALL игнорироваться: новое необязательное поле не
делает курсор недействительным для реплик прежней версии.
#### Scenario: Курсор другого чата
@@ -30,7 +31,8 @@
- **WHEN** клиент раскодирует курсор, выданный историей чата или
списком чатов, и меняет в нём только одно: ключ последнего элемента —
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
кодирует обратно и передаёт в тот же список
верхнем регистре, либо версию — на `true`; затем кодирует обратно и
передаёт в тот же список
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
раскодированный и закодированный обратно без изменений, даёт 200
раскодированный и закодированный обратно без изменений или с
добавленным незнакомым полем, даёт 200 и ту же страницу
+37 -8
View File
@@ -132,42 +132,42 @@
(обратная сборка).
Проверка: названные в правиле файлы и тип существуют.
- [ ] 3.6 Commit исправления и правила (после подтверждения; сообщение
- [x] 3.6 Commit исправления и правила (после подтверждения; сообщение
вроде `fix: reject tampered cursors and non-canonical UUIDs`).
Проверка: `git status` чист.
## 4. Стенд и регрессия (решение 6)
- [ ] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
- [x] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
`make lb_stats` — оба слота `UP` на новом образе, `make instances` —
`instances: 2`.
- [ ] 4.2 `make test` и `make student_test` через LB. Проверка:
- [x] 4.2 `make test` и `make student_test` через LB. Проверка:
- `PASS` и все тесты прошли, включая тесты реплик;
- в журнале реплик за время прогона нет ответов 500 (`make logs`,
access-лог, поле статуса).
- [ ] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
- [x] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов
удалён.
- [ ] 4.4 Чистый clone во временном проекте compose на нестандартных
- [x] 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 на
- [x] 4.5 Спросить пользователя о полной проверке из чистого clone на
портах по умолчанию (`evidence/tests/clean-clone-final.md`): она
удаляет рабочий стенд с volume. Без согласия — не делать и записать
в 5.1, что не делалась.
## 5. Документы
- [ ] 5.1 `evidence/tests/strict-id-validation-checks.md`:
- [x] 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`:
- [x] 5.2 `REPORT.md`:
- строка в таблице доказательств: строгий вход с UUID и курсор, red →
green, ссылка на 5.1;
- расхождение с прежним поведением: запись UUID без дефисов,
@@ -185,6 +185,35 @@
- [ ] 5.5 Commit документов (после подтверждения; сообщение вроде `docs:
record strict-id-validation checks`). Проверка: `git status` чист.
## 7. Пересмотр в apply: проверка полей курсора (до 5.5)
По просьбе пользователя обратная сборка из 3.3 заменена проверкой полей
(design, решение 2 и «Пересмотр в apply»).
- [x] 7.1 Артефакты: дельта и основной спек `pagination` (незнакомые
поля игнорируются; «добавляет поле» — не 400, а 200 и та же страница),
design, proposal. Проверка: `openspec validate strict-id-validation
--strict` и `openspec validate --specs` без ошибок.
- [x] 7.2 `decode_cursor`: `type(v) is int`, `t`/`i` — строки,
`str(UUID(i)) == i`, без обратной сборки. Проверка: `uv run python -c`
— 19 подмен дают только `CursorError`, без изменений / лишнее поле /
padding / пробелы / порядок ключей — тот же ключ.
- [x] 7.3 `test_pagination.py`: `CURSOR_CHANGES` (+ `v=1.0`, без
лишнего поля) и `CURSOR_KEPT` (без изменений, лишнее поле → 200 и та
же страница).
- [x] 7.4 Правило `api-contract.md`: проверка полей, почему без обратной
сборки, смена формата — новая `CURSOR_VERSION` и приём обеих на время
замены.
- [x] 7.5 `make lint`, `make test_isolated` — все тесты зелёные.
- [x] 7.6 Commit смягчения (сообщение вроде `fix: check cursor fields
instead of re-encoding`).
- [ ] 7.7 Регрессия на этом commit, как 4.1–4.4: `make rolling_update`
с `628b5f2`, `make test` и `make student_test` через LB (0 ответов 5xx),
`make failure_checks`, `git clone` во временном проекте на
нестандартных портах.
- [ ] 7.8 evidence (5.1) и `REPORT.md` (5.2) — под проверку полей и
числа 7.5–7.7.
## 6. Завершение
- [ ] 6.1 `/opsx:verify strict-id-validation`. Найденное исправить
+9 -7
View File
@@ -62,11 +62,12 @@
для другого чата, для списка чатов вместо истории или наоборот, либо
повреждённая строка SHALL давать 400 `invalid_request`.
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
если он по-прежнему разбирается: ключ элемента другого типа или в другой
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
страницу списка.
если он по-прежнему разбирается: ключ элемента другого типа или не в той
записи, в которой его выдал сервер, версия другого значения или типа.
Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых
сервер не знает, SHALL игнорироваться: новое необязательное поле не
делает курсор недействительным для реплик прежней версии.
#### Scenario: Курсор другого чата
@@ -84,7 +85,8 @@
- **WHEN** клиент раскодирует курсор, выданный историей чата или
списком чатов, и меняет в нём только одно: ключ последнего элемента —
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
кодирует обратно и передаёт в тот же список
верхнем регистре, либо версию — на `true`; затем кодирует обратно и
передаёт в тот же список
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
раскодированный и закодированный обратно без изменений, даёт 200
раскодированный и закодированный обратно без изменений или с
добавленным незнакомым полем, даёт 200 и ту же страницу
+14 -11
View File
@@ -5,10 +5,12 @@
привязывает курсор к конкретному списку: курсор чужого чата или списка
чатов другого пользователя не разбирается.
Принимается только та запись, которую выдал сервер: после разбора курсор
собирается заново и сравнивается с полученной строкой. Так изменённый
клиентом курсор (`"v": true`, лишнее поле, id или время в другой записи)
— ошибка, а не страница.
Поля проверяются по отдельности: `v` — ровно целое 1, `t` и `i` — строки,
`i` — в записи сервера (8-4-4-4-12, нижний регистр). Так изменённый
клиентом курсор — ошибка, а не 500 и не страница. Незнакомые поля
игнорируются: необязательное поле можно добавить, не ломая курсоры реплик
прежней версии при поочерёдной замене. Формат, который прежний код не
прочтёт, — новая `v`, и на время замены сервер принимает обе.
"""
import base64
@@ -53,8 +55,8 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
"""Ключ последнего элемента предыдущей страницы.
Бросает `CursorError`, если курсор не разбирается, другой версии,
выдан для другой области или отличается от записи, которую выдал бы
`encode_cursor` для того же ключа.
выдан для другой области или его поля не того типа и не в той
записи, в которой их пишет `encode_cursor`.
"""
try:
padded = cursor + "=" * (-len(cursor) % 4)
@@ -64,7 +66,9 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
if not isinstance(payload, dict):
raise CursorError("malformed cursor")
if payload.get("v") != CURSOR_VERSION:
version = payload.get("v")
# bool — подкласс int: без проверки типа true прошло бы как 1
if type(version) is not int or version != CURSOR_VERSION:
raise CursorError("unsupported cursor version")
if payload.get("s") != scope:
raise CursorError("cursor belongs to another list")
@@ -78,8 +82,7 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
item_id = UUID(raw_id)
except ValueError as e:
raise CursorError("malformed cursor") from e
issued = encode_cursor(scope=scope, created_at=created_at, item_id=item_id)
if issued != cursor:
raise CursorError("cursor was changed")
# UUID() принимает и запись без дефисов, в верхнем регистре, с urn:uuid:
if str(item_id) != raw_id:
raise CursorError("malformed cursor")
return created_at, item_id
+19 -5
View File
@@ -15,8 +15,9 @@ from contract import assert_error, assert_errors, assert_ok
# подмена в содержимом курсора: какие поля заменить
type Change = Callable[[dict[str, Any]], dict[str, Any]]
# подмены выданного курсора (сценарий «Изменённый курсор»): ключ элемента
# не строка, тот же id в другой записи, версия true, лишнее поле
# подмены выданного курсора, которые дают 400 (сценарий «Изменённый
# курсор»): ключ элемента не строка, тот же id в другой записи, версия
# не ровно целое 1
CURSOR_CHANGES: dict[str, Change] = {
"i=[]": lambda _: {"i": []},
"i={}": lambda _: {"i": {}},
@@ -25,6 +26,12 @@ CURSOR_CHANGES: dict[str, Change] = {
"i without hyphens": lambda payload: {"i": payload["i"].replace("-", "")},
"i upper case": lambda payload: {"i": payload["i"].upper()},
"v=true": lambda _: {"v": True},
"v=1.0": lambda _: {"v": 1.0},
}
# и которые принимаются: незнакомое поле игнорируется, иначе новое
# необязательное поле ломало бы курсоры при поочерёдной замене реплик
CURSOR_KEPT: dict[str, Change] = {
"unchanged": lambda _: {},
"extra field": lambda _: {"x": 1},
}
@@ -236,9 +243,16 @@ 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)
schema = issued.listing.schema
# контроль: без подмены и с незнакомым полем — та же вторая страница
second = assert_ok(page(cursor=issued.cursor), 200, schema)
for name, change in CURSOR_KEPT.items():
kept = assert_ok(
page(cursor=tamper(issued.cursor, change)),
200,
schema,
)
assert kept == second, f"{name}: another page"
assert_errors(
{
name: page(cursor=tamper(issued.cursor, change))