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:
@@ -172,13 +172,24 @@ FastAPI 0.141 из `uv.lock`:
|
|||||||
или пользователя, битая base64 или JSON → 400. Последний элемент
|
или пользователя, битая base64 или JSON → 400. Последний элемент
|
||||||
предыдущей страницы не повторяется. `limit` между страницами можно
|
предыдущей страницы не повторяется. `limit` между страницами можно
|
||||||
менять.
|
менять.
|
||||||
- Курсор принимается только в записи, которую выдал сервер:
|
- Изменённый курсор — 400, а не 500 и не страница (спек `pagination`,
|
||||||
`decode_cursor` после разбора собирает его заново (`encode_cursor`) и
|
«Изменённый курсор»). `decode_cursor` проверяет поля по отдельности
|
||||||
сравнивает со входом. Изменённый курсор — `"i"` не строка, тот же id в
|
(change `strict-id-validation`):
|
||||||
другой записи, `"v": true`, лишнее поле — 400, а не 500 и не страница
|
- `v` — ровно целое 1 (`type(v) is int`: `True == 1`);
|
||||||
(спек `pagination`, «Изменённый курсор»). Значения курсора до
|
- `t` и `i` — строки до `strptime` и `UUID()`: `UUID()` на не-строке
|
||||||
`UUID()` и `strptime` проверяются на тип: `UUID()` на не-строке роняет
|
роняет `AttributeError`, а не `ValueError`;
|
||||||
`AttributeError`, а не `ValueError` (change `strict-id-validation`).
|
- `i` — в записи сервера, `str(UUID(i)) == i`.
|
||||||
|
- Незнакомые поля курсора игнорируются, и курсор не сравнивается с
|
||||||
|
обратной сборкой (`encode_cursor(...) == cursor`): иначе формат закрыт,
|
||||||
|
и даже совместимая правка (необязательное поле, порядок ключей,
|
||||||
|
`to_rfc3339`, общий с ответами) давала бы 400 курсорам реплики другой
|
||||||
|
версии во время `make rolling_update`. Тесты такое окно не ловят:
|
||||||
|
курсор в них выдаёт и проверяет один код.
|
||||||
|
- Формат курсора, который прежний код не прочтёт (переименованное поле,
|
||||||
|
другая запись времени), — новая `CURSOR_VERSION`. На время замены
|
||||||
|
реплик новая версия принимает и старую `v`: курсор, выданный старой
|
||||||
|
репликой, приходит на новую. Старую версию убирать отдельной правкой,
|
||||||
|
когда старых реплик не осталось.
|
||||||
- Семантику при конкурентных вставках и ограничения часов описать в
|
- Семантику при конкурентных вставках и ограничения часов описать в
|
||||||
`REPORT.md` (например: `created_at` монотонен внутри чата).
|
`REPORT.md` (например: `created_at` монотонен внутри чата).
|
||||||
- В Postgres порядок и курсор задаёт SQL: сравнение кортежей
|
- В Postgres порядок и курсор задаёт SQL: сравнение кортежей
|
||||||
|
|||||||
@@ -48,8 +48,9 @@
|
|||||||
|
|
||||||
- Никакой ввод в `cursor`, `chat_id` и `member_ids` не даёт 500.
|
- Никакой ввод в `cursor`, `chat_id` и `member_ids` не даёт 500.
|
||||||
- Вход с UUID — ровно `format: uuid` контракта; ответы не меняются.
|
- Вход с UUID — ровно `format: uuid` контракта; ответы не меняются.
|
||||||
- Курсор принимается только таким, каким его выдал сервер. Формат
|
- Подменённый курсор — 400. Формат при этом остаётся открытым для
|
||||||
выдачи прежний: курсоры от реплик до замены работают и после неё.
|
совместимых правок: незнакомые поля игнорируются. Формат выдачи
|
||||||
|
прежний: курсоры от реплик до замены работают и после неё.
|
||||||
- Каждый новый сценарий спека — тест black-box. Тесты курсора и записи
|
- Каждый новый сценарий спека — тест black-box. Тесты курсора и записи
|
||||||
UUID красные на текущем коде, это показано в evidence.
|
UUID красные на текущем коде, это показано в evidence.
|
||||||
|
|
||||||
@@ -107,37 +108,39 @@ UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)]
|
|||||||
сообщения не доходит до сервиса, ключ идемпотентности не занимается
|
сообщения не доходит до сервиса, ключ идемпотентности не занимается
|
||||||
(сценарий `idempotency` «Невалидный запрос не занимает ключ»).
|
(сценарий `idempotency` «Невалидный запрос не занимает ключ»).
|
||||||
|
|
||||||
### 2. Курсор — проверка обратной сборкой
|
### 2. Курсор — проверка полей, незнакомые поля игнорируются
|
||||||
|
|
||||||
`decode_cursor` после разбора собирает курсор заново из разобранных
|
`decode_cursor` после разбора base64url и JSON проверяет поля по
|
||||||
значений и сравнивает с полученной строкой:
|
отдельности:
|
||||||
|
|
||||||
1. base64url и JSON → объект; `s == scope` (как сейчас);
|
1. объект; `v` — ровно целое `1`. Тип проверяется отдельно: `bool` —
|
||||||
2. `t` и `i` — строки (`isinstance(..., str)`), иначе `CursorError`.
|
подкласс `int`, и `True == 1` прошло бы прежнее сравнение;
|
||||||
|
2. `s == scope` (как сейчас);
|
||||||
|
3. `t` и `i` — строки (`isinstance(..., str)`), иначе `CursorError`.
|
||||||
Тогда `from_rfc3339` и `UUID` бросают только `ValueError`, и
|
Тогда `from_rfc3339` и `UUID` бросают только `ValueError`, и
|
||||||
`except` сужается до него;
|
`except` сужается до него;
|
||||||
3. `encode_cursor(scope=…, created_at=…, item_id=…) == cursor`, иначе
|
4. `i` — в записи сервера: `str(UUID(i)) == i` (8-4-4-4-12, нижний
|
||||||
`CursorError("malformed cursor")`.
|
регистр). Запись UUID от версии кода не зависит, так что эта проверка
|
||||||
|
формат на будущее не закрывает.
|
||||||
|
|
||||||
Шаг 3 одной проверкой ловит всё, чего сервер не выдаёт:
|
Принимаются, потому что разбираются в тот же ключ:
|
||||||
|
|
||||||
- `"v": true` или `1.0` (`True == 1` проходит проверку версии);
|
- незнакомые поля — игнорируются;
|
||||||
- `"i"` без дефисов, в верхнем регистре, с `urn:uuid:`;
|
- пробелы и порядок ключей в JSON;
|
||||||
- `"t"` с другим числом знаков дробной части или однозначным месяцем
|
- padding `=`.
|
||||||
(`strptime` нестрог);
|
|
||||||
- лишние поля, другой порядок ключей, пробелы в JSON, padding `=`.
|
|
||||||
|
|
||||||
Проверка версии (`v != 1` → «unsupported cursor version») остаётся
|
Формат, который прежний код не прочтёт (переименованное поле, другой
|
||||||
отдельной: у неё своё сообщение и смысл на будущее.
|
формат времени), — новая версия `v`. На время `make rolling_update`
|
||||||
|
новая версия принимает обе: курсор, выданный старой репликой, приходит
|
||||||
Стоимость — одна сериализация JSON и base64 на запрос страницы с
|
на новую (правило `api-contract.md`, «Пагинация (keyset)»).
|
||||||
курсором, единицы микросекунд.
|
|
||||||
|
|
||||||
| Вариант | Почему не он |
|
| Вариант | Почему не он |
|
||||||
|---|---|
|
|---|---|
|
||||||
| Добавить `AttributeError` в `except` | правка в одно слово, но ловит слишком широко (может скрыть настоящий дефект) и не трогает `v: true` и другие записи — курсор остаётся «разбирается, значит годен» |
|
| Добавить `AttributeError` в `except` | правка в одно слово, но ловит слишком широко (может скрыть настоящий дефект) и не трогает `v: true` и другие записи — курсор остаётся «разбирается, значит годен» |
|
||||||
| Только проверки типов | убирает 500, но подменённый курсор в другой записи по-прежнему даёт страницу — расходится с «изменённый курсор → 400» |
|
| Только проверки типов | убирает 500, но подменённый курсор (`v: true`, id в другой записи) по-прежнему даёт страницу — расходится с «изменённый курсор → 400» |
|
||||||
| Проверка каждого поля по отдельности (`type(v) is int`, шаблон для `i`, точная длина `t`) | несколько правил там, где хватает одного инварианта, и легко забыть следующее поле |
|
| Обратная сборка: `encode_cursor(...) == cursor` | первая реализация (`628b5f2`), заменена в apply по просьбе пользователя (раздел «Пересмотр в apply») |
|
||||||
|
| Отвергать незнакомые поля | тот же закрытый формат: необязательное поле нового кода давало бы 400 на старых репликах во время замены |
|
||||||
|
| Строгая запись `t`: `to_rfc3339(from_rfc3339(t)) == t` | связывает курсор с форматом времени ответов API (`to_rfc3339` общий). Нестрогая запись времени разбирается в позицию того же списка, вреда нет |
|
||||||
|
|
||||||
### 3. Без подписи курсора
|
### 3. Без подписи курсора
|
||||||
|
|
||||||
@@ -150,7 +153,7 @@ HMAC сделал бы подмену невозможной, но:
|
|||||||
- **угрозы нет:** область `s` уже привязывает курсор к своему списку.
|
- **угрозы нет:** область `s` уже привязывает курсор к своему списку.
|
||||||
Подменённый ключ сдвигает позицию только внутри списка, который
|
Подменённый ключ сдвигает позицию только внутри списка, который
|
||||||
пользователь и так вправе читать. Требование — 400 вместо 500 и
|
пользователь и так вправе читать. Требование — 400 вместо 500 и
|
||||||
вместо страницы, и обратная сборка его выполняет.
|
вместо страницы, и проверка полей его выполняет.
|
||||||
|
|
||||||
### 4. Тесты: подмена настоящего курсора и некрасный контроль
|
### 4. Тесты: подмена настоящего курсора и некрасный контроль
|
||||||
|
|
||||||
@@ -165,9 +168,11 @@ HMAC сделал бы подмену невозможной, но:
|
|||||||
отсекается до места дефекта, и тест был бы зелёным без
|
отсекается до места дефекта, и тест был бы зелёным без
|
||||||
исправления. Ровно так устроен нынешний `test_garbage_cursor`
|
исправления. Ровно так устроен нынешний `test_garbage_cursor`
|
||||||
(`{"x":1}` останавливается на версии).
|
(`{"x":1}` останавливается на версии).
|
||||||
- **Варианты:** `"i"` = `[]`, `{}`, `123`, `false` (сейчас 500), тот же
|
- **Варианты → 400:** `"i"` = `[]`, `{}`, `123`, `false` (сейчас 500),
|
||||||
id без дефисов и в верхнем регистре, `"v": true`, лишнее поле
|
тот же id без дефисов и в верхнем регистре, `"v": true` и `1.0`
|
||||||
(сейчас 200).
|
(сейчас 200).
|
||||||
|
- **Варианты → 200 и та же страница:** без изменений и с лишним полем
|
||||||
|
(незнакомые поля игнорируются).
|
||||||
- **Оба списка:** история (два сообщения, `limit=1`) и список чатов
|
- **Оба списка:** история (два сообщения, `limit=1`) и список чатов
|
||||||
(два чата, `limit=1`).
|
(два чата, `limit=1`).
|
||||||
- **`member_ids`** (`test_chats.py`).
|
- **`member_ids`** (`test_chats.py`).
|
||||||
@@ -231,7 +236,33 @@ change. Вывод — в `evidence/tests/strict-id-validation-checks.md`
|
|||||||
- **[Тест курсора знает его внутренний формат]** → если формат
|
- **[Тест курсора знает его внутренний формат]** → если формат
|
||||||
изменится, упадёт контрольное утверждение хелпера, и тест покраснеет,
|
изменится, упадёт контрольное утверждение хелпера, и тест покраснеет,
|
||||||
а не пройдёт молча. Формат меняют вместе с тестом.
|
а не пройдёт молча. Формат меняют вместе с тестом.
|
||||||
- **[Будущая версия курсора]** → обратная сборка сравнивает с текущим
|
- **[Несовместимая правка формата курсора]** → новая `v`, на время
|
||||||
`encode_cursor`. Новая версия меняет обе функции и тест вместе.
|
замены реплик принимаются обе (правило `api-contract.md`). Тесты этого
|
||||||
|
окна не проверяют: курсор в них выдаёт и проверяет один код.
|
||||||
- **[Текст ошибки]** → 400 содержит место и сообщение pydantic (`path.chat_id: Value error, must be a UUID in 8-4-4-4-12 form`) без
|
- **[Текст ошибки]** → 400 содержит место и сообщение pydantic (`path.chat_id: Value error, must be a UUID in 8-4-4-4-12 form`) без
|
||||||
входного значения — как у остальных ошибок валидации (`errors.py`).
|
входного значения — как у остальных ошибок валидации (`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
|
## What Changes
|
||||||
|
|
||||||
- **Курсор принимается только в записи, которую выдал сервер.**
|
- **Подменённый курсор — 400.**
|
||||||
- Значения не того типа больше не роняют разбор.
|
- Значения не того типа больше не роняют разбор.
|
||||||
- Подмена любого поля — `"i"`, `"t"`, `"v"`, лишнее поле, другая
|
- Ключ элемента не строка или не в записи сервера, версия не ровно
|
||||||
запись UUID или времени — даёт 400 `invalid_request`, а не 500 и не
|
целое 1 — 400 `invalid_request`, а не 500 и не 200.
|
||||||
200.
|
- Незнакомые поля игнорируются: формат остаётся открытым для
|
||||||
|
совместимых правок, и курсоры не ломаются при поочерёдной замене
|
||||||
|
реплик (design, «Пересмотр в apply»).
|
||||||
- **UUID на входе — только запись 8-4-4-4-12.** Это `chat_id` в пути трёх
|
- **UUID на входе — только запись 8-4-4-4-12.** Это `chat_id` в пути трёх
|
||||||
ручек (`GET /chats/{chat_id}`, `GET` и `POST
|
ручек (`GET /chats/{chat_id}`, `GET` и `POST
|
||||||
/chats/{chat_id}/messages`) и элементы `member_ids` в `POST /chats`.
|
/chats/{chat_id}/messages`) и элементы `member_ids` в `POST /chats`.
|
||||||
|
|||||||
@@ -8,11 +8,12 @@
|
|||||||
для другого чата, для списка чатов вместо истории или наоборот, либо
|
для другого чата, для списка чатов вместо истории или наоборот, либо
|
||||||
повреждённая строка SHALL давать 400 `invalid_request`.
|
повреждённая строка SHALL давать 400 `invalid_request`.
|
||||||
|
|
||||||
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
|
|
||||||
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
||||||
если он по-прежнему разбирается: ключ элемента другого типа или в другой
|
если он по-прежнему разбирается: ключ элемента другого типа или не в той
|
||||||
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
|
записи, в которой его выдал сервер, версия другого значения или типа.
|
||||||
страницу списка.
|
Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых
|
||||||
|
сервер не знает, SHALL игнорироваться: новое необязательное поле не
|
||||||
|
делает курсор недействительным для реплик прежней версии.
|
||||||
|
|
||||||
#### Scenario: Курсор другого чата
|
#### Scenario: Курсор другого чата
|
||||||
|
|
||||||
@@ -30,7 +31,8 @@
|
|||||||
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
||||||
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
||||||
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
||||||
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
|
верхнем регистре, либо версию — на `true`; затем кодирует обратно и
|
||||||
кодирует обратно и передаёт в тот же список
|
передаёт в тот же список
|
||||||
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
||||||
раскодированный и закодированный обратно без изменений, даёт 200
|
раскодированный и закодированный обратно без изменений или с
|
||||||
|
добавленным незнакомым полем, даёт 200 и ту же страницу
|
||||||
|
|||||||
@@ -132,42 +132,42 @@
|
|||||||
(обратная сборка).
|
(обратная сборка).
|
||||||
|
|
||||||
Проверка: названные в правиле файлы и тип существуют.
|
Проверка: названные в правиле файлы и тип существуют.
|
||||||
- [ ] 3.6 Commit исправления и правила (после подтверждения; сообщение
|
- [x] 3.6 Commit исправления и правила (после подтверждения; сообщение
|
||||||
вроде `fix: reject tampered cursors and non-canonical UUIDs`).
|
вроде `fix: reject tampered cursors and non-canonical UUIDs`).
|
||||||
Проверка: `git status` чист.
|
Проверка: `git status` чист.
|
||||||
|
|
||||||
## 4. Стенд и регрессия (решение 6)
|
## 4. Стенд и регрессия (решение 6)
|
||||||
|
|
||||||
- [ ] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
|
- [x] 4.1 `make replicas`, затем `make rolling_update`. Проверка:
|
||||||
`make lb_stats` — оба слота `UP` на новом образе, `make instances` —
|
`make lb_stats` — оба слота `UP` на новом образе, `make instances` —
|
||||||
`instances: 2`.
|
`instances: 2`.
|
||||||
- [ ] 4.2 `make test` и `make student_test` через LB. Проверка:
|
- [x] 4.2 `make test` и `make student_test` через LB. Проверка:
|
||||||
- `PASS` и все тесты прошли, включая тесты реплик;
|
- `PASS` и все тесты прошли, включая тесты реплик;
|
||||||
- в журнале реплик за время прогона нет ответов 500 (`make logs`,
|
- в журнале реплик за время прогона нет ответов 500 (`make logs`,
|
||||||
access-лог, поле статуса).
|
access-лог, поле статуса).
|
||||||
- [ ] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
|
- [x] 4.3 `make failure_checks`. Проверка: все проверки отказов прошли,
|
||||||
сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов
|
сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов
|
||||||
удалён.
|
удалён.
|
||||||
- [ ] 4.4 Чистый clone во временном проекте compose на нестандартных
|
- [x] 4.4 Чистый clone во временном проекте compose на нестандартных
|
||||||
портах, по процедуре `evidence/replicas/clean-clone-ports.md`:
|
портах, по процедуре `evidence/replicas/clean-clone-ports.md`:
|
||||||
`git clone` commit 3.6, `make run_docker`, `make test`, `make
|
`git clone` commit 3.6, `make run_docker`, `make test`, `make
|
||||||
student_test` через LB клона, затем `down -v` клона. Проверка:
|
student_test` через LB клона, затем `down -v` клона. Проверка:
|
||||||
всё код 0, рабочий стенд `mtusi-lab3` не тронут.
|
всё код 0, рабочий стенд `mtusi-lab3` не тронут.
|
||||||
- [ ] 4.5 Спросить пользователя о полной проверке из чистого clone на
|
- [x] 4.5 Спросить пользователя о полной проверке из чистого clone на
|
||||||
портах по умолчанию (`evidence/tests/clean-clone-final.md`): она
|
портах по умолчанию (`evidence/tests/clean-clone-final.md`): она
|
||||||
удаляет рабочий стенд с volume. Без согласия — не делать и записать
|
удаляет рабочий стенд с volume. Без согласия — не делать и записать
|
||||||
в 5.1, что не делалась.
|
в 5.1, что не делалась.
|
||||||
|
|
||||||
## 5. Документы
|
## 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, число тестов, причины
|
- красный прогон 2.6 и зелёный 3.4 — commit, число тестов, причины
|
||||||
падений;
|
падений;
|
||||||
- 4.1–4.4 и решение по 4.5.
|
- 4.1–4.4 и решение по 4.5.
|
||||||
|
|
||||||
Только обезличенные выводы, без токенов и паролей
|
Только обезличенные выводы, без токенов и паролей
|
||||||
(`evidence/README.md`).
|
(`evidence/README.md`).
|
||||||
- [ ] 5.2 `REPORT.md`:
|
- [x] 5.2 `REPORT.md`:
|
||||||
- строка в таблице доказательств: строгий вход с UUID и курсор, red →
|
- строка в таблице доказательств: строгий вход с UUID и курсор, red →
|
||||||
green, ссылка на 5.1;
|
green, ссылка на 5.1;
|
||||||
- расхождение с прежним поведением: запись UUID без дефисов,
|
- расхождение с прежним поведением: запись UUID без дефисов,
|
||||||
@@ -185,6 +185,35 @@
|
|||||||
- [ ] 5.5 Commit документов (после подтверждения; сообщение вроде `docs:
|
- [ ] 5.5 Commit документов (после подтверждения; сообщение вроде `docs:
|
||||||
record strict-id-validation checks`). Проверка: `git status` чист.
|
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. Завершение
|
||||||
|
|
||||||
- [ ] 6.1 `/opsx:verify strict-id-validation`. Найденное исправить
|
- [ ] 6.1 `/opsx:verify strict-id-validation`. Найденное исправить
|
||||||
|
|||||||
@@ -62,11 +62,12 @@
|
|||||||
для другого чата, для списка чатов вместо истории или наоборот, либо
|
для другого чата, для списка чатов вместо истории или наоборот, либо
|
||||||
повреждённая строка SHALL давать 400 `invalid_request`.
|
повреждённая строка SHALL давать 400 `invalid_request`.
|
||||||
|
|
||||||
Сервер SHALL принимать курсор только в той записи, в которой его выдал.
|
|
||||||
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
||||||
если он по-прежнему разбирается: ключ элемента другого типа или в другой
|
если он по-прежнему разбирается: ключ элемента другого типа или не в той
|
||||||
записи, другая версия, лишнее поле. Такой курсор MUST NOT давать 500 или
|
записи, в которой его выдал сервер, версия другого значения или типа.
|
||||||
страницу списка.
|
Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых
|
||||||
|
сервер не знает, SHALL игнорироваться: новое необязательное поле не
|
||||||
|
делает курсор недействительным для реплик прежней версии.
|
||||||
|
|
||||||
#### Scenario: Курсор другого чата
|
#### Scenario: Курсор другого чата
|
||||||
|
|
||||||
@@ -84,7 +85,8 @@
|
|||||||
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
||||||
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
||||||
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
||||||
верхнем регистре, либо версию — на `true`, либо добавляет поле; затем
|
верхнем регистре, либо версию — на `true`; затем кодирует обратно и
|
||||||
кодирует обратно и передаёт в тот же список
|
передаёт в тот же список
|
||||||
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
||||||
раскодированный и закодированный обратно без изменений, даёт 200
|
раскодированный и закодированный обратно без изменений или с
|
||||||
|
добавленным незнакомым полем, даёт 200 и ту же страницу
|
||||||
|
|||||||
+14
-11
@@ -5,10 +5,12 @@
|
|||||||
привязывает курсор к конкретному списку: курсор чужого чата или списка
|
привязывает курсор к конкретному списку: курсор чужого чата или списка
|
||||||
чатов другого пользователя не разбирается.
|
чатов другого пользователя не разбирается.
|
||||||
|
|
||||||
Принимается только та запись, которую выдал сервер: после разбора курсор
|
Поля проверяются по отдельности: `v` — ровно целое 1, `t` и `i` — строки,
|
||||||
собирается заново и сравнивается с полученной строкой. Так изменённый
|
`i` — в записи сервера (8-4-4-4-12, нижний регистр). Так изменённый
|
||||||
клиентом курсор (`"v": true`, лишнее поле, id или время в другой записи)
|
клиентом курсор — ошибка, а не 500 и не страница. Незнакомые поля
|
||||||
— ошибка, а не страница.
|
игнорируются: необязательное поле можно добавить, не ломая курсоры реплик
|
||||||
|
прежней версии при поочерёдной замене. Формат, который прежний код не
|
||||||
|
прочтёт, — новая `v`, и на время замены сервер принимает обе.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
import base64
|
import base64
|
||||||
@@ -53,8 +55,8 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
|
|||||||
"""Ключ последнего элемента предыдущей страницы.
|
"""Ключ последнего элемента предыдущей страницы.
|
||||||
|
|
||||||
Бросает `CursorError`, если курсор не разбирается, другой версии,
|
Бросает `CursorError`, если курсор не разбирается, другой версии,
|
||||||
выдан для другой области или отличается от записи, которую выдал бы
|
выдан для другой области или его поля не того типа и не в той
|
||||||
`encode_cursor` для того же ключа.
|
записи, в которой их пишет `encode_cursor`.
|
||||||
"""
|
"""
|
||||||
try:
|
try:
|
||||||
padded = cursor + "=" * (-len(cursor) % 4)
|
padded = cursor + "=" * (-len(cursor) % 4)
|
||||||
@@ -64,7 +66,9 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
|
|||||||
|
|
||||||
if not isinstance(payload, dict):
|
if not isinstance(payload, dict):
|
||||||
raise CursorError("malformed cursor")
|
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")
|
raise CursorError("unsupported cursor version")
|
||||||
if payload.get("s") != scope:
|
if payload.get("s") != scope:
|
||||||
raise CursorError("cursor belongs to another list")
|
raise CursorError("cursor belongs to another list")
|
||||||
@@ -78,8 +82,7 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
|
|||||||
item_id = UUID(raw_id)
|
item_id = UUID(raw_id)
|
||||||
except ValueError as e:
|
except ValueError as e:
|
||||||
raise CursorError("malformed cursor") from e
|
raise CursorError("malformed cursor") from e
|
||||||
|
# UUID() принимает и запись без дефисов, в верхнем регистре, с urn:uuid:
|
||||||
issued = encode_cursor(scope=scope, created_at=created_at, item_id=item_id)
|
if str(item_id) != raw_id:
|
||||||
if issued != cursor:
|
raise CursorError("malformed cursor")
|
||||||
raise CursorError("cursor was changed")
|
|
||||||
return created_at, item_id
|
return created_at, item_id
|
||||||
|
|||||||
@@ -15,8 +15,9 @@ from contract import assert_error, assert_errors, assert_ok
|
|||||||
# подмена в содержимом курсора: какие поля заменить
|
# подмена в содержимом курсора: какие поля заменить
|
||||||
type Change = Callable[[dict[str, Any]], dict[str, Any]]
|
type Change = Callable[[dict[str, Any]], dict[str, Any]]
|
||||||
|
|
||||||
# подмены выданного курсора (сценарий «Изменённый курсор»): ключ элемента
|
# подмены выданного курсора, которые дают 400 (сценарий «Изменённый
|
||||||
# не строка, тот же id в другой записи, версия true, лишнее поле
|
# курсор»): ключ элемента не строка, тот же id в другой записи, версия
|
||||||
|
# не ровно целое 1
|
||||||
CURSOR_CHANGES: dict[str, Change] = {
|
CURSOR_CHANGES: dict[str, Change] = {
|
||||||
"i=[]": lambda _: {"i": []},
|
"i=[]": lambda _: {"i": []},
|
||||||
"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 without hyphens": lambda payload: {"i": payload["i"].replace("-", "")},
|
||||||
"i upper case": lambda payload: {"i": payload["i"].upper()},
|
"i upper case": lambda payload: {"i": payload["i"].upper()},
|
||||||
"v=true": lambda _: {"v": True},
|
"v=true": lambda _: {"v": True},
|
||||||
|
"v=1.0": lambda _: {"v": 1.0},
|
||||||
|
}
|
||||||
|
# и которые принимаются: незнакомое поле игнорируется, иначе новое
|
||||||
|
# необязательное поле ломало бы курсоры при поочерёдной замене реплик
|
||||||
|
CURSOR_KEPT: dict[str, Change] = {
|
||||||
|
"unchanged": lambda _: {},
|
||||||
"extra field": lambda _: {"x": 1},
|
"extra field": lambda _: {"x": 1},
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -236,9 +243,16 @@ def test_tampered_cursor(issued: IssuedCursor) -> None:
|
|||||||
"""Курсор не собирается с нуля: с чужими `v` или `s` его отсекла бы
|
"""Курсор не собирается с нуля: с чужими `v` или `s` его отсекла бы
|
||||||
проверка версии или области раньше разбора ключа."""
|
проверка версии или области раньше разбора ключа."""
|
||||||
page = issued.listing.page
|
page = issued.listing.page
|
||||||
# контроль: тот же курсор, перекодированный без подмены, принимается
|
schema = issued.listing.schema
|
||||||
unchanged = tamper(issued.cursor, lambda _: {})
|
# контроль: без подмены и с незнакомым полем — та же вторая страница
|
||||||
assert_ok(page(cursor=unchanged), 200, 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(
|
assert_errors(
|
||||||
{
|
{
|
||||||
name: page(cursor=tamper(issued.cursor, change))
|
name: page(cursor=tamper(issued.cursor, change))
|
||||||
|
|||||||
Reference in New Issue
Block a user